{ "openapi": "3.1.0", "info": { "title": "SoundSync Public API", "version": "2026-10-24", "description": "Documentation revision, not a new versioning guarantee. Each operation labels reviewed field schemas or operation-directory coverage. A missing schema is not an empty-body contract. Follow conditional fields, authentication, error handling, and evidence boundaries in the linked guide; source review is not seeded E2 coverage of every operation." }, "servers": [ { "url": "https://www.soundsync.dev" } ], "components": { "securitySchemes": { "AccountSession": { "type": "http", "scheme": "bearer", "description": "The account token for this operation; developer workspace permissions and customer ownership are still enforced." }, "PartnerApiKey": { "type": "http", "scheme": "bearer", "description": "Relationship-scoped partner API credential; not a plugin key or account JWT." }, "LibraryToken": { "type": "http", "scheme": "bearer", "description": "Customer library/download token. It is not interchangeable with an account JWT." }, "ProductAppId": { "type": "apiKey", "in": "header", "name": "x-ss-app-id" }, "ProductPluginKey": { "type": "apiKey", "in": "header", "name": "x-ss-plugin-key" }, "ProductPluginSecret": { "type": "apiKey", "in": "header", "name": "x-ss-plugin-secret" }, "ProductId": { "type": "apiKey", "in": "header", "name": "x-ss-product-id" }, "NativePublicClient": { "type": "apiKey", "in": "header", "name": "x-soundsync-public-client", "description": "Generated hise-native or juce-native public identity, not customer authorization. The request still needs its operation-specific entitlement/machine proof." }, "FrameToken": { "type": "apiKey", "in": "query", "name": "frameToken", "description": "Short-lived token issued for this embedded frame, not an account or product credential." }, "LegacyDownloadToken": { "type": "http", "scheme": "bearer", "description": "Legacy serial/download authorization. Use the current entitlement-delivery flow for new clients." }, "LegacyDownloadQueryToken": { "type": "apiKey", "in": "query", "name": "token", "description": "Private legacy download token; never publish token-bearing URLs." } }, "schemas": { "ApiError": { "type": "object", "properties": { "ok": { "const": false }, "code": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" }, "error": { "type": "string" }, "field": { "type": "string" }, "retryable": { "type": "boolean" }, "localCancellationSaved": { "type": "boolean" } }, "additionalProperties": true } } }, "paths": { "/api/account/2fa/disable": { "post": { "summary": "Disable your enrolled authenticator", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/account-security" }, "parameters": [], "responses": { "200": { "description": "200: confirmation message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in personal account only; not an effective developer workspace or product assignment.", "x-request-fields": [ "currentPassword: string (required)", "code: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/accountRoutes.js", "controllers/accountController.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string" }, "code": { "type": "string" } }, "required": [ "currentPassword", "code" ], "additionalProperties": true } } } } } }, "/api/account/2fa/enable": { "post": { "summary": "Confirm a code from the pending authenticator", "description": "Personal account enrollment, not a workspace operation. The pending secret is checked under a row lock and consumed in the same transaction that saves the verified authenticator and recovery hashes. Concurrent or repeated enable requests return 409 after one succeeds; they do not rotate a live factor or return another recovery set. An invalid code or failed save leaves enrollment uncommitted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/account-security" }, "parameters": [], "responses": { "200": { "description": "200: message and single-use recoveryCodes. Save them privately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "recoveryCodes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in personal account only; not an effective developer workspace or product assignment.", "x-request-fields": [ "code: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/accountRoutes.js", "controllers/accountController.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ], "additionalProperties": true } } } } } }, "/api/account/2fa/setup": { "post": { "summary": "Begin authenticator enrollment", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/account-security" }, "parameters": [], "responses": { "200": { "description": "200: secret, otpauthUrl, issuer. Treat the entire response as private.", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" }, "otpauthUrl": { "type": "string" }, "issuer": { "const": "SoundSync" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in personal account only; not an effective developer workspace or product assignment.", "x-request-fields": [ "currentPassword: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/accountRoutes.js", "controllers/accountController.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string" } }, "required": [ "currentPassword" ], "additionalProperties": true } } } } } }, "/api/account/email-change/verify": { "get": { "summary": "Open the email-change verification page", "description": "Shows a confirmation form without consuming the token or changing the email. GET and HEAD are safe for email scanners. The customer must submit Confirm email change; token validity and email conflicts are checked by POST. Responses are not cached.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" } ], "responses": { "200": { "description": "HTTP 200: text/html.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "text/html": { "schema": { "type": "string" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "text/html": { "schema": { "type": "string" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query token: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/accountEmailVerificationRoutes.js", "controllers/accountController.js", "services/customerInformationUpdateService.js" ] }, "post": { "summary": "Verify an email change and return JSON", "description": "The private email token authorizes confirmation without a login session. JSON requests return JSON; browser form submissions return HTML with the same outcome. Reconfirming a completed change succeeds only while that address is still current. Expired, replaced or cancelled links cannot change the address; request a new link from the account.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: message, email.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "additionalProperties": true } }, "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "text/html": { "schema": { "type": "string" } } } }, "410": { "description": "The requested token or saved operation has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "text/html": { "schema": { "type": "string" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }, "text/html": { "schema": { "type": "string" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "token: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/accountEmailVerificationRoutes.js", "controllers/accountController.js", "services/customerInformationUpdateService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": true } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": true } } } } } }, "/api/account/profile": { "put": { "summary": "Update profile details or request an email change", "description": "Names can be cleared independently. An email change requires verification; this response is not proof that the email changed. first_name, last_name and avatar_url aliases are accepted. Issued invoices and sent messages are not rewritten.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: message, emailChangeRequested, emailDelivery, user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "emailChangeRequested": { "type": "boolean" }, "emailDelivery": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "user": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "is_reseller": { "type": "boolean" }, "phone": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in personal account only; not an effective developer workspace or product assignment.", "x-request-fields": [ "firstName: string,null", "lastName: string,null", "phone: string,null", "email: string", "avatarUrl: string,null" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/accountRoutes.js", "controllers/accountController.js", "services/customerInformationUpdateService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email" }, "avatarUrl": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } } } }, "/api/account/security": { "get": { "summary": "Read your account security status", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/account-security" }, "parameters": [], "responses": { "200": { "description": "200: current account security status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "role": { "type": "string" } }, "additionalProperties": true }, "security": { "type": "object", "properties": { "twoFactorEnabled": { "type": "boolean" }, "twoFactorSetupPending": { "type": "boolean" }, "recoveryCodesRemaining": { "type": "integer", "minimum": 0 }, "activeSessionCount": { "type": "integer", "minimum": 0 }, "twoFactorEnabledAt": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in personal account only; not an effective developer workspace or product assignment.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/accountRoutes.js", "controllers/accountController.js" ] } }, "/api/account/update-password": { "post": { "summary": "Change the password using the current password", "description": "Send currentPassword (or oldPassword) and newPassword. Password verification, replacement and other-session revocation run in one transaction. If revocation fails, the password change rolls back and the request fails. The recognized current token is retained where present; with no current token all account sessions are revoked.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: message, code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in personal account only; not an effective developer workspace or product assignment.", "x-request-fields": [ "currentPassword: string", "oldPassword: string", "newPassword: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/accountRoutes.js", "controllers/accountController.js", "services/customerInformationUpdateService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string" }, "oldPassword": { "type": "string" }, "newPassword": { "type": "string", "minLength": 8 } }, "required": [ "newPassword" ], "additionalProperties": true } } } } } }, "/api/auth/forgot-password": { "post": { "summary": "Request account password recovery", "description": "The response does not disclose whether the email has an account. A storefront context selects customer recovery; invitation recovery requires account_type. Reset delivery is separate from this HTTP success.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: message, code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "email: string (required)", "account_type: customer | platform", "storefrontSlug: string", "resetBaseUrl: string", "origin: string", "programInviteToken: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js", "services/passwordResetService.js", "services/customerMarketingChoiceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "account_type": { "type": "string", "enum": [ "customer", "platform" ] }, "storefrontSlug": { "type": "string" }, "resetBaseUrl": { "type": "string" }, "origin": { "type": "string" }, "programInviteToken": { "type": "string" } }, "required": [ "email" ], "additionalProperties": true } } } } } }, "/api/auth/hise-login": { "get": { "summary": "Legacy GET account login compatibility route", "description": "Use POST /api/auth/login with a JSON body for all new clients, including JUCE. This alias shares the normal login rate-limit bucket. Legacy account/email/password query aliases are accepted, but URLs can expose credentials through logging and history; never put them in examples, screenshots or support reports. hise_text or format=hise_text returns the legacy text transport after successful sign-in. MFA challenges must be completed through the supported POST flow. Route presence does not imply that JUCE requires HISE authentication.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [ { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "password", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "hise_text", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: token, accessToken, customerToken, user, twoFactorRequired, twoFactorToken, code, message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "user": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "twoFactorRequired": { "type": "boolean" }, "twoFactorToken": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired credentials or sign-in challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Only the matching verified account. Legacy first-party compatibility, not a HISE requirement or recommended new integration.", "x-request-fields": [ "query email: string", "query password: string", "query role: string", "query format: string", "query hise_text: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js" ], "deprecated": true } }, "/api/auth/login": { "post": { "summary": "Sign in or complete a two-factor challenge", "description": "A wrong or expired challenge returns 401. Never store or log the password, authenticator setup secret, recovery code, or tokens in public examples.", "externalDocs": { "url": "https://www.soundsync.dev/docs/account-security" }, "parameters": [], "responses": { "200": { "description": "200: account result and token, or twoFactorRequired and twoFactorToken. A challenge token is not an account session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "user": { "type": "object", "properties": {}, "additionalProperties": true }, "twoFactorRequired": { "type": "boolean" }, "twoFactorToken": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired credentials or sign-in challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Only the matching verified account.", "x-request-fields": [ "email: string (required)", "password: string", "twoFactorToken: string", "twoFactorCode: string", "role: string", "marketingOptIn: boolean", "marketingOptOut: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "twoFactorToken": { "type": "string" }, "twoFactorCode": { "type": "string" }, "role": { "type": "string" }, "marketingOptIn": { "type": "boolean" }, "marketingOptOut": { "type": "boolean" } }, "required": [ "email" ], "additionalProperties": true, "anyOf": [ { "required": [ "password" ] }, { "required": [ "twoFactorToken", "twoFactorCode" ] } ] } } } } } }, "/api/auth/logout": { "post": { "summary": "Revoke the presented account session", "description": "Revokes the presented account session, not every account session. A failed session deletion returns 503 SESSION_REVOCATION_UNAVAILABLE; it is not a completed sign-out. Retry instead of assuming server revocation from client-side token removal.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: ok.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "SESSION_REVOCATION_UNAVAILABLE" ], "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js", "services/passwordResetService.js", "services/customerMarketingChoiceService.js" ] } }, "/api/auth/me": { "get": { "summary": "Read the signed-in account", "description": "Returns the current account, not a customer list or developer workspace authorization.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "is_reseller": { "type": "boolean" }, "phone": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js", "services/passwordResetService.js", "services/customerMarketingChoiceService.js" ] } }, "/api/auth/partner-program-verification": { "post": { "summary": "Request another verification email for an eligible program invitation", "description": "Rate-limited by IP and normalized email. Returns the same generic 200 message whether or not mail is queued; it does not disclose account existence or prove delivery. Checks invitation expiry, current terms, recipient identity, account status and cooldown. Does not accept an agreement, create earnings or sign in the recipient.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "additionalProperties": true } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Public invitation recovery; the private invitation must match an eligible unverified recipient account.", "x-request-fields": [ "email: string (required)", "programInviteToken: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "programInviteToken": { "type": "string" } }, "required": [ "email", "programInviteToken" ], "additionalProperties": true } } } } } }, "/api/auth/register": { "post": { "summary": "Create an account and request email verification", "description": "Registration creates an unverified account, not a signed-in session. The optional logo is a multipart file. Account role and invitations are validated by the server; protected signup configurations can reject registration. A failed marketing-choice save can return 503 with accountCreated: true; do not create another account.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "202": { "description": "HTTP 202: ok, code, status, emailVerificationRequired, emailSent, message, user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "code": { "type": "string" }, "status": { "type": "string" }, "emailVerificationRequired": { "type": "boolean" }, "emailSent": { "type": "boolean" }, "message": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "is_reseller": { "type": "boolean" }, "phone": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "email: string (required)", "password: string (required)", "firstName: string", "lastName: string", "role: customer | developer", "account_type: customer | platform", "storefrontSlug: string", "company_name: string", "website_url: string", "support_email: string", "support_url: string", "business_address: string", "tax_id: string", "brand_color: string", "dark_mode: boolean", "custom_domain: string", "billing_email: string", "partnerInviteToken: string", "programInviteToken: string", "marketingOptIn: boolean", "marketingOptOut: boolean", "logo: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js", "services/passwordResetService.js", "services/customerMarketingChoiceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 1 }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "role": { "type": "string", "enum": [ "customer", "developer" ] }, "account_type": { "type": "string", "enum": [ "customer", "platform" ] }, "storefrontSlug": { "type": "string" }, "company_name": { "type": "string" }, "website_url": { "type": "string" }, "support_email": { "type": "string", "format": "email" }, "support_url": { "type": "string" }, "business_address": { "type": "string" }, "tax_id": { "type": "string" }, "brand_color": { "type": "string" }, "dark_mode": { "type": "boolean" }, "custom_domain": { "type": "string" }, "billing_email": { "type": "string", "format": "email" }, "partnerInviteToken": { "type": "string" }, "programInviteToken": { "type": "string" }, "marketingOptIn": { "type": "boolean" }, "marketingOptOut": { "type": "boolean" }, "logo": { "type": "string", "format": "binary" } }, "required": [ "email", "password" ], "additionalProperties": true } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 1 }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "role": { "type": "string", "enum": [ "customer", "developer" ] }, "account_type": { "type": "string", "enum": [ "customer", "platform" ] }, "storefrontSlug": { "type": "string" }, "company_name": { "type": "string" }, "website_url": { "type": "string" }, "support_email": { "type": "string", "format": "email" }, "support_url": { "type": "string" }, "business_address": { "type": "string" }, "tax_id": { "type": "string" }, "brand_color": { "type": "string" }, "dark_mode": { "type": "boolean" }, "custom_domain": { "type": "string" }, "billing_email": { "type": "string", "format": "email" }, "partnerInviteToken": { "type": "string" }, "programInviteToken": { "type": "string" }, "marketingOptIn": { "type": "boolean" }, "marketingOptOut": { "type": "boolean" }, "logo": { "type": "string", "format": "binary" } }, "required": [ "email", "password" ], "additionalProperties": true } } } } } }, "/api/auth/reset-password": { "post": { "summary": "Consume a private one-time reset token", "description": "Aliases resetToken/reset_token and password are accepted. The token is private and one-use; a successful reset revokes sessions. Invalid or expired tokens do not create a session.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: message, code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "token: string (required)", "newPassword: string (required)", "programInviteToken: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js", "services/passwordResetService.js", "services/customerMarketingChoiceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "newPassword": { "type": "string", "minLength": 8 }, "programInviteToken": { "type": "string" } }, "required": [ "token", "newPassword" ], "additionalProperties": true } } } } } }, "/api/auth/storefront-bridge/issue": { "post": { "summary": "Prepare a customer session handoff to a branded storefront", "description": "First-party customer sign-in handoff. Issues a private, origin-bound, single-use token with a five-minute lifetime. Storefront slug aliases are supported. This creates a bridge record; it is not a zero-write readiness probe. Never publish the token or send it to another origin.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: bridgeToken, expiresAt, origin, storefrontSlug.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bridgeToken": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "origin": { "type": "string" }, "storefrontSlug": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Verified customer account session and an allowed published storefront origin. Not developer workspace access.", "x-request-fields": [ "origin: string (required)", "storefrontSlug: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "CUSTOMER_SESSION_REQUIRED", "STOREFRONT_ORIGIN_NOT_ALLOWED" ], "x-source-files": [ "routes/authRoutes.js", "services/storefrontAuthBridgeService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "origin": { "type": "string" }, "storefrontSlug": { "type": "string" } }, "required": [ "origin" ], "additionalProperties": true } } } } } }, "/api/auth/storefront-bridge/redeem": { "post": { "summary": "Exchange a private handoff token for a storefront customer session", "description": "Consumes the token atomically, checks the customer account and records a 30-day customer session. If an Origin header and body origin are both present, they must match. Expired or consumed tokens return 401. The exchange is not whole-workflow atomic: a later failure can consume the bridge without returning a session. Obtain a new bridge through the existing signed-in account instead of replaying it. An HTTP 200 does not prove the browser successfully stored the session.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: token, accessToken, customerToken, user, storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "accessToken": { "type": "string" }, "customerToken": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "role": { "const": "customer" } }, "additionalProperties": true }, "storefront": { "type": "object", "properties": { "developerId": { "type": "integer", "minimum": 1 }, "storefrontId": { "type": [ "integer", "null" ] }, "slug": { "type": "string" }, "origin": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired credentials or sign-in challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Private bridge token, its allowed origin and storefront. No account JWT is required for the exchange itself.", "x-request-fields": [ "bridgeToken: string (required)", "origin: string (required)", "storefrontSlug: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "BRIDGE_TOKEN_REQUIRED", "BRIDGE_TOKEN_INVALID", "STOREFRONT_BRIDGE_ORIGIN_MISMATCH", "STOREFRONT_ORIGIN_NOT_ALLOWED", "CUSTOMER_SESSION_UNAVAILABLE" ], "x-source-files": [ "routes/authRoutes.js", "services/storefrontAuthBridgeService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bridgeToken": { "type": "string" }, "origin": { "type": "string" }, "storefrontSlug": { "type": "string" } }, "required": [ "bridgeToken", "origin" ], "additionalProperties": true } } } } } }, "/api/auth/verify-email": { "get": { "summary": "Consume an account verification link and display HTML", "description": "Consumes a private one-use verification token and returns HTML, including on POST. Successful verification does not create a signed-in session. Open the supported sign-in continuation; never poll, log or share a verification URL. Missing/expired/used tokens return 400 HTML, not the generic JSON error model.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" }, { "name": "storefrontSlug", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "program_invite", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: text/html.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "text/html": { "schema": { "type": "string" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "text/html": { "schema": { "type": "string" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query token: string (required)", "query storefrontSlug: string", "query program_invite: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js" ] }, "post": { "summary": "Consume an account verification token and return HTML", "description": "Consumes a private one-use verification token and returns HTML, including on POST. Successful verification does not create a signed-in session. Open the supported sign-in continuation; never poll, log or share a verification URL. Missing/expired/used tokens return 400 HTML, not the generic JSON error model.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/accounts" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: text/html.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "text/html": { "schema": { "type": "string" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "text/html": { "schema": { "type": "string" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "token: string (required)", "storefrontSlug: string", "program_invite: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/authRoutes.js", "controllers/authController.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "storefrontSlug": { "type": "string" }, "program_invite": { "type": "string" } }, "required": [ "token" ], "additionalProperties": true } } } } } }, "/api/checkout/payment-methods": { "get": { "summary": "Read the currently configured checkout payment choices.", "description": "Side effects: None.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/checkout" }, "parameters": [], "responses": { "200": { "description": "200 { methods: { stripe, paypal } }. Provider configuration does not prove that a particular product or subscription is eligible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "methods": { "type": "object", "properties": { "stripe": { "type": "boolean" }, "paypal": { "type": "boolean" } }, "required": [ "stripe", "paypal" ], "additionalProperties": true } }, "required": [ "methods" ], "additionalProperties": true } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Configured platform payment methods, without customer or product ownership data.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productCheckoutRoutes.js" ] } }, "/api/checkout/product": { "post": { "summary": "Create Stripe or PayPal managed checkout, or resolve a supported free claim.", "description": "Follow the returned provider URL. PayPal supports one-time purchases, not subscriptions. Subscription checkout uses Stripe and one subscription product per request. Server pricing, the $9.99 paid floor, account verification, billing eligibility and commerce controls remain authoritative. Never grant access from a browser return alone. Side effects: Records checkout_started analytics, stores checkout session, records abandoned checkout signal, may create free order/entitlement for free claims.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/checkout" }, "parameters": [], "responses": { "200": { "description": "Successful idempotent replay or duplicate confirmation; inspect the linked operation contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "enum": [ "stripe", "paypal", "manual" ] }, "checkoutSessionId": { "type": "string" }, "url": { "type": "string" }, "orderId": { "type": "integer", "minimum": 1 }, "paypalMode": { "type": "string" }, "stripeMode": { "type": "string" }, "freeClaim": { "type": "boolean" }, "alreadyClaimed": { "type": "boolean" }, "claimed": { "type": "boolean" }, "checkoutBypassed": { "type": "boolean" } }, "additionalProperties": true } } } }, "201": { "description": "201 with provider stripe or paypal, checkoutSessionId, url and applicable stripeMode/paypalMode/saleChannel. A supported free claim returns provider manual with freeClaim, claimed, alreadyClaimed, orderId and url; an existing claim returns 200 rather than 201.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "enum": [ "stripe", "paypal", "manual" ] }, "checkoutSessionId": { "type": "string" }, "url": { "type": "string" }, "orderId": { "type": "integer", "minimum": 1 }, "paypalMode": { "type": "string" }, "stripeMode": { "type": "string" }, "freeClaim": { "type": "boolean" }, "alreadyClaimed": { "type": "boolean" }, "claimed": { "type": "boolean" }, "checkoutBypassed": { "type": "boolean" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product owner, storefront ownership, marketplace attribution, and customer identity are resolved server-side.", "x-request-fields": [ "productId: integer", "quantity: integer", "items: array", "promoCode: string", "taxQuoteId: string", "storefrontSlug: string", "paymentProvider: stripe | paypal", "marketingOptIn: boolean", "marketingOptOut: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productCheckoutRoutes.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "productId" ], "additionalProperties": true } }, "promoCode": { "type": "string" }, "taxQuoteId": { "type": "string" }, "storefrontSlug": { "type": "string" }, "paymentProvider": { "enum": [ "stripe", "paypal" ] }, "marketingOptIn": { "type": "boolean" }, "marketingOptOut": { "type": "boolean" } }, "additionalProperties": true, "anyOf": [ { "required": [ "productId" ] }, { "required": [ "items" ] } ] } } } } } }, "/api/checkout/quote": { "post": { "summary": "Create a server tax/checkout quote for product checkout.", "description": "When internal tax checkout is active, checkout session creation requires a valid server quote. Side effects: Creates quote/calculation rows when internal tax engine is active.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/checkout" }, "parameters": [], "responses": { "201": { "description": "201 quote with tax, total, jurisdiction, platform/developer allocation and expiry when internal tax checkout is enabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "quoteId": { "type": "string" }, "currency": { "type": "string" }, "subtotalCents": { "type": "integer", "minimum": 0 }, "taxAmountCents": { "type": "integer", "minimum": 0 }, "totalCents": { "type": "integer", "minimum": 0 }, "supported": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Optional authentication OR Account Bearer JWT", "x-access-scope": "Use the authentication and resource scope specified for this operation.", "x-request-fields": [ "productId: integer", "items: array", "countryCode: string", "regionCode: string", "postalCode: string", "promoCode: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ {}, { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productCheckoutRoutes.js", "services/checkoutQuoteService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "productId" ], "additionalProperties": true } }, "countryCode": { "type": "string" }, "regionCode": { "type": "string" }, "postalCode": { "type": "string" }, "promoCode": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/checkout/tax-jurisdictions": { "get": { "summary": "List checkout-supported tax jurisdictions.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/checkout" }, "parameters": [], "responses": { "200": { "description": "countries[] supported by the internal tax jurisdiction service.", "content": { "application/json": { "schema": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "object", "properties": { "countryCode": { "type": "string" }, "countryName": { "type": "string" }, "regions": { "type": "array", "items": { "type": "object", "properties": { "regionCode": { "type": "string" }, "regionName": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Use the authentication and resource scope specified for this operation.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productCheckoutRoutes.js", "services/checkoutQuoteService.js" ] } }, "/api/dashboard/command-center": { "get": { "summary": "Read the permission-filtered business command center", "description": "First-party dashboard contract. customers.view gates private customer snapshots; billing.view gates billing state and current-month charges; settlements.view gates balances; partners.view gates reseller health. Private order/refund activity follows orders.view/refunds.view. Restricted sections are unavailable, not zero activity. Request query/body data cannot add permissions. A partial response means heavy aggregates timed out or failed, not verified zero sales. Readiness and supported reporting paths can initialize supporting records; do not use this as a zero-write public uptime probe. Package labels reflect recorded JUCE/HISE generation or remain framework-neutral. No HISE package is required for a JUCE product; saved credentials, generated packages and successful connection proof are distinct.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/workspace-dashboard" }, "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "enum": [ "usd", "USD" ] } }, { "name": "environment", "in": "query", "required": false, "schema": { "enum": [ "test", "live" ] } } ], "responses": { "200": { "description": "HTTP 200: range, period_start, period_end, currency, environment, partial, fallback_reason, access, kpis, customer_snapshot, customerSnapshot, current_month_charges, revenue_breakdown, revenue_snapshot, revenueSnapshot, business_health, businessHealth, attention, action_center, actionCenter, recent_activity, activity_feed, activityFeed, products, product_health, productHealth, integrations, goals, marketplace, developer_health_score, developerHealthScore, opportunities, backend_gaps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "partial": { "type": "boolean" }, "fallback_reason": { "type": "string" }, "access": { "type": "object", "properties": { "customers": { "type": "boolean" }, "billing": { "type": "boolean" }, "settlements": { "type": "boolean" }, "orders": { "type": "boolean" }, "refunds": { "type": "boolean" }, "marketing": { "type": "boolean" }, "partners": { "type": "boolean" }, "manageGoals": { "type": "boolean" } }, "additionalProperties": true }, "kpis": { "type": "object", "properties": { "revenue": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "sales": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "subscriptions": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "customers": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "products": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "downloads": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "activations": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "external_redemptions": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "customer_snapshot": { "anyOf": [ { "type": "object", "properties": { "new_this_month": { "type": "integer" }, "returning_percentage": { "type": "number" }, "countries_count": { "type": "integer" }, "top_country": { "type": "string" }, "top_country_percentage": { "type": "number" }, "recent_customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "country": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "href": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, { "type": "object", "properties": { "available": { "const": false }, "restricted": { "const": true }, "requiredPermission": { "type": "string" } }, "required": [ "available", "restricted", "requiredPermission" ], "additionalProperties": true } ] }, "customerSnapshot": { "anyOf": [ { "type": "object", "properties": { "new_this_month": { "type": "integer" }, "returning_percentage": { "type": "number" }, "countries_count": { "type": "integer" }, "top_country": { "type": "string" }, "top_country_percentage": { "type": "number" }, "recent_customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "country": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "href": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, { "type": "object", "properties": { "available": { "const": false }, "restricted": { "const": true }, "requiredPermission": { "type": "string" } }, "required": [ "available", "restricted", "requiredPermission" ], "additionalProperties": true } ] }, "current_month_charges": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean" }, "marketing_email_charges_cents": { "type": "integer" }, "redemption_overage_charges_cents": { "type": "integer" }, "minimum_adjustment_cents": { "type": "integer" }, "current_total_if_billed_today_cents": { "type": "integer" }, "pre_minimum_total_cents": { "type": "integer" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "lineItems": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "marketing_emails": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "external_redemptions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, { "type": "object", "properties": { "available": { "const": false }, "restricted": { "const": true }, "requiredPermission": { "type": "string" } }, "required": [ "available", "restricted", "requiredPermission" ], "additionalProperties": true } ] }, "revenue_breakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "revenue_snapshot": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "revenueSnapshot": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "business_health": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessHealth": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "attention": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "action_center": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "actionCenter": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "recent_activity": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "activity_feed": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "activityFeed": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "product_health": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "productHealth": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "integrations": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "href": { "type": "string" } }, "additionalProperties": true } }, "last_plugin_connection": { "type": [ "object", "null" ] } }, "additionalProperties": true }, "goals": { "type": "object", "properties": { "month": { "type": "string" }, "revenue_goal_cents": { "type": "integer" }, "downloads_goal": { "type": "integer" }, "customer_goal": { "type": "integer" }, "products_goal": { "type": "integer" }, "persisted": { "type": "boolean" }, "canManage": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "current": { "type": "number" }, "target": { "type": "number" }, "unit": { "type": "string" }, "percentage": { "type": "number" } }, "additionalProperties": true } } }, "additionalProperties": true }, "marketplace": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "developer_health_score": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "developerHealthScore": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "opportunities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "backend_gaps": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Sensitive sections require their own matching permission.", "x-request-fields": [ "query range: string", "query currency: value", "query environment: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/dashboardRoutes.js", "services/developerDashboardLaunchCenterService.js", "services/developerReadinessService.js" ] } }, "/api/dashboard/goals": { "get": { "summary": "Read saved monthly workspace goals", "description": "Returns the current monthly goals or a default empty goal configuration. Reading goals is not authorization to change them.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/workspace-dashboard" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: month, revenue_goal_cents, downloads_goal, customer_goal, products_goal, persisted, canManage, items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string" }, "revenue_goal_cents": { "type": "integer" }, "downloads_goal": { "type": "integer" }, "customer_goal": { "type": "integer" }, "products_goal": { "type": "integer" }, "persisted": { "type": "boolean" }, "canManage": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "current": { "type": "number" }, "target": { "type": "number" }, "unit": { "type": "string" }, "percentage": { "type": "number" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/dashboardRoutes.js", "services/developerDashboardLaunchCenterService.js", "services/developerReadinessService.js" ] }, "put": { "summary": "Save monthly workspace goals", "description": "Whole-goal replacement, not a sparse update: omitted targets become zero. Values are rounded and clamped to nonnegative integers; revenue_goal/revenueGoal are dollar aliases, while revenue_goal_cents/revenueGoalCents are cents. Omit month for the current UTC month; send a valid date such as 2026-10-01 for an explicit month. A successful write returns persisted:true. Saving a target changes no product prices, fees, payout settings or financial flags.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/workspace-dashboard" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: month, revenue_goal_cents, downloads_goal, customer_goal, products_goal, persisted, canManage, items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string" }, "revenue_goal_cents": { "type": "integer" }, "downloads_goal": { "type": "integer" }, "customer_goal": { "type": "integer" }, "products_goal": { "type": "integer" }, "persisted": { "type": "boolean" }, "canManage": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "current": { "type": "number" }, "target": { "type": "number" }, "unit": { "type": "string" }, "percentage": { "type": "number" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view, settings.manage and all-products scope; current fixed roles permit owner/administrator writes.", "x-request-fields": [ "month: string", "revenue_goal_cents: number", "revenueGoalCents: number", "revenue_goal: number", "revenueGoal: number", "downloads_goal: number", "downloadsGoal: number", "customer_goal: number", "customerGoal: number", "products_goal: number", "productsGoal: number" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "developer_team_permission_denied", "DASHBOARD_GOALS_TABLE_MISSING" ], "x-source-files": [ "routes/dashboardRoutes.js", "services/developerDashboardLaunchCenterService.js", "services/developerReadinessService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string", "format": "date" }, "revenue_goal_cents": { "type": "number" }, "revenueGoalCents": { "type": "number" }, "revenue_goal": { "type": "number" }, "revenueGoal": { "type": "number" }, "downloads_goal": { "type": "number" }, "downloadsGoal": { "type": "number" }, "customer_goal": { "type": "number" }, "customerGoal": { "type": "number" }, "products_goal": { "type": "number" }, "productsGoal": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/dashboard/launch-center": { "get": { "summary": "Read launch checks and permission-filtered business dashboard", "description": "First-party dashboard contract. customers.view gates private customer snapshots; billing.view gates billing state and current-month charges; settlements.view gates balances; partners.view gates reseller health. Private order/refund activity follows orders.view/refunds.view. Restricted sections are unavailable, not zero activity. Request query/body data cannot add permissions. A partial response means heavy aggregates timed out or failed, not verified zero sales. Readiness and supported reporting paths can initialize supporting records; do not use this as a zero-write public uptime probe. Package labels reflect recorded JUCE/HISE generation or remain framework-neutral. No HISE package is required for a JUCE product; saved credentials, generated packages and successful connection proof are distinct.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/workspace-dashboard" }, "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "schema": { "enum": [ "usd", "USD" ] } }, { "name": "environment", "in": "query", "required": false, "schema": { "enum": [ "test", "live" ] } } ], "responses": { "200": { "description": "HTTP 200: developer_id, generated_at, goLiveReady, completionPercent, status, blockingCount, warningCount, readiness, nextAction, checklist, issues, summaryCards, counts, health, commandCenter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "developer_id": { "type": "integer", "minimum": 1 }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "goLiveReady": { "type": "boolean" }, "completionPercent": { "type": "number" }, "status": { "type": "string" }, "blockingCount": { "type": "integer" }, "warningCount": { "type": "integer" }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "nextAction": { "type": [ "object", "null" ] }, "checklist": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "summaryCards": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "counts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "health": { "type": "object", "properties": { "products": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "storefront": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "marketplace": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "billing": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "accountStatus": { "type": [ "string", "null" ] }, "currentInvoiceStatus": { "type": [ "string", "null" ] }, "pastDue": { "type": "boolean" }, "amountDueCents": { "type": "integer" }, "failedAmountCents": { "type": "integer" } }, "additionalProperties": true }, { "type": "object", "properties": { "available": { "const": false }, "restricted": { "const": true }, "requiredPermission": { "type": "string" } }, "required": [ "available", "restricted", "requiredPermission" ], "additionalProperties": true } ] }, "settlement": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "accountStatus": { "type": [ "string", "null" ] }, "payoutHold": { "type": "boolean" }, "availableBalanceCents": { "type": "integer" }, "pendingBalanceCents": { "type": "integer" }, "payoutMethodStatus": { "type": [ "string", "null" ] } }, "additionalProperties": true }, { "type": "object", "properties": { "available": { "const": false }, "restricted": { "const": true }, "requiredPermission": { "type": "string" } }, "required": [ "available", "restricted", "requiredPermission" ], "additionalProperties": true } ] }, "reseller": { "anyOf": [ { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, { "type": "object", "properties": { "available": { "const": false }, "restricted": { "const": true }, "requiredPermission": { "type": "string" } }, "required": [ "available", "restricted", "requiredPermission" ], "additionalProperties": true } ] }, "expansion": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "commandCenter": { "type": "object", "properties": { "range": { "type": "string" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "partial": { "type": "boolean" }, "fallback_reason": { "type": "string" }, "access": { "type": "object", "properties": { "customers": { "type": "boolean" }, "billing": { "type": "boolean" }, "settlements": { "type": "boolean" }, "orders": { "type": "boolean" }, "refunds": { "type": "boolean" }, "marketing": { "type": "boolean" }, "partners": { "type": "boolean" }, "manageGoals": { "type": "boolean" } }, "additionalProperties": true }, "kpis": { "type": "object", "properties": { "revenue": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "sales": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "subscriptions": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "customers": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "products": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "downloads": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "activations": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "external_redemptions": { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "source": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "customer_snapshot": { "anyOf": [ { "type": "object", "properties": { "new_this_month": { "type": "integer" }, "returning_percentage": { "type": "number" }, "countries_count": { "type": "integer" }, "top_country": { "type": "string" }, "top_country_percentage": { "type": "number" }, "recent_customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "country": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "href": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, { "type": "object", "properties": { "available": { "const": false }, "restricted": { "const": true }, "requiredPermission": { "type": "string" } }, "required": [ "available", "restricted", "requiredPermission" ], "additionalProperties": true } ] }, "customerSnapshot": { "anyOf": [ { "type": "object", "properties": { "new_this_month": { "type": "integer" }, "returning_percentage": { "type": "number" }, "countries_count": { "type": "integer" }, "top_country": { "type": "string" }, "top_country_percentage": { "type": "number" }, "recent_customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "country": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "href": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, { "type": "object", "properties": { "available": { "const": false }, "restricted": { "const": true }, "requiredPermission": { "type": "string" } }, "required": [ "available", "restricted", "requiredPermission" ], "additionalProperties": true } ] }, "current_month_charges": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean" }, "marketing_email_charges_cents": { "type": "integer" }, "redemption_overage_charges_cents": { "type": "integer" }, "minimum_adjustment_cents": { "type": "integer" }, "current_total_if_billed_today_cents": { "type": "integer" }, "pre_minimum_total_cents": { "type": "integer" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "lineItems": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "marketing_emails": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "external_redemptions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, { "type": "object", "properties": { "available": { "const": false }, "restricted": { "const": true }, "requiredPermission": { "type": "string" } }, "required": [ "available", "restricted", "requiredPermission" ], "additionalProperties": true } ] }, "revenue_breakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "revenue_snapshot": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "revenueSnapshot": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "business_health": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessHealth": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "attention": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "action_center": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "actionCenter": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "recent_activity": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "activity_feed": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "activityFeed": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "product_health": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "productHealth": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "integrations": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "href": { "type": "string" } }, "additionalProperties": true } }, "last_plugin_connection": { "type": [ "object", "null" ] } }, "additionalProperties": true }, "goals": { "type": "object", "properties": { "month": { "type": "string" }, "revenue_goal_cents": { "type": "integer" }, "downloads_goal": { "type": "integer" }, "customer_goal": { "type": "integer" }, "products_goal": { "type": "integer" }, "persisted": { "type": "boolean" }, "canManage": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "current": { "type": "number" }, "target": { "type": "number" }, "unit": { "type": "string" }, "percentage": { "type": "number" } }, "additionalProperties": true } } }, "additionalProperties": true }, "marketplace": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "developer_health_score": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "developerHealthScore": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "opportunities": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "backend_gaps": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Sensitive sections require their own matching permission.", "x-request-fields": [ "query range: string", "query currency: value", "query environment: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/dashboardRoutes.js", "services/developerDashboardLaunchCenterService.js", "services/developerReadinessService.js" ] } }, "/api/delivery/entitlements/{entitlementId}/files/{fileIndex}": { "get": { "summary": "Authorizes an active customer entitlement and redirects to short-lived signed R2 delivery.", "description": "This endpoint keeps authorization and download accounting in SoundSync while R2 serves the file bytes directly. fileIndex is zero-based. Token ownership, active entitlement, expansion rules and file existence are checked before redirect. Do not persist the storage URL as a permanent download. When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks. Side effects: Logs delivery and updates legacy serial download count when the entitlement metadata includes a serialId.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/downloads" }, "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fileIndex", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "download_token", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "libraryToken", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "302": { "description": "302 redirect to a short-lived signed R2 download URL, or JSON error for missing token, invalid entitlement/file index, inactive entitlement, expansion block, missing file, upstream failure, or delivery failure.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Short-lived authorized private download URL." } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Customer library/download token", "x-access-scope": "Entitlement, customer identity, product, source/sourceId, expansion rule, and file-index scoped.", "x-request-fields": [ "query token: string", "query download_token: string", "query libraryToken: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "LibraryToken": [] } ], "x-contract-coverage": "Reviewed transport contract; inspect the redirect/response headers and operation-specific authorization.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "SESSION_VERIFICATION_UNAVAILABLE", "LIBRARY_SESSION_REVOKED" ], "x-source-files": [ "routes/deliveryRoutes.js", "controllers/deliveryController.js", "services/customerLibraryIdentityService.js" ] } }, "/api/developer/abandoned-checkout-settings": { "get": { "summary": "Read abandoned-checkout reminder settings", "description": "These are developer-wide settings, not separate policies per product. Product context resolves the owning developer; delegated calls should supply an assigned productId. PUT defaults delayHours to 24 and accepts delay_hours. Saving does not send a message or bypass audience eligibility and suppression.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "delayHours": { "type": "integer", "minimum": 1, "maximum": 168 } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view and all-products scope. Product context must belong to the effective developer.", "x-request-fields": [ "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaCommerceService.js" ] }, "put": { "summary": "Save abandoned-checkout reminder settings", "description": "These are developer-wide settings, not separate policies per product. Product context resolves the owning developer; delegated calls should supply an assigned productId. PUT defaults delayHours to 24 and accepts delay_hours. Saving does not send a message or bypass audience eligibility and suppression.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "delayHours": { "type": "integer", "minimum": 1, "maximum": 168 } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.manage and all-products scope. Product context must belong to the effective developer.", "x-request-fields": [ "query productId: integer", "enabled: boolean", "delayHours: integer", "productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaCommerceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "delayHours": { "type": "integer", "minimum": 1, "maximum": 168 }, "productId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } } } }, "/api/developer/activity": { "get": { "summary": "Read workspace activity", "description": "Customer identity requires customers.view; serials require serials.view; order IDs require orders.view; entitlement IDs require entitlements.view. Restricted fields are null. Opaque messages, actor details and nested metadata require all four record permissions plus refunds.view. Client query/body fields cannot grant permissions.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "description": "" }, { "name": "eventType", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "developerId": { "type": "integer", "minimum": 1 }, "actorType": { "type": [ "string", "null" ] }, "actorUserId": { "type": [ "integer", "null" ] }, "customerId": { "type": [ "integer", "null" ] }, "customerEmail": { "type": [ "string", "null" ] }, "customerName": { "type": [ "string", "null" ] }, "productId": { "type": [ "integer", "null" ] }, "productName": { "type": [ "string", "null" ] }, "serialId": { "type": [ "integer", "null" ] }, "serialCode": { "type": [ "string", "null" ] }, "entitlementId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "orderId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "eventType": { "type": "string" }, "severity": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products scope.", "x-request-fields": [ "query limit: integer", "query eventType: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js", "services/platformEventService.js" ] } }, "/api/developer/ai/operations/analytics-summary": { "post": { "summary": "Draft an explanation of current analytics", "description": "Requires configured operational AI availability and quota. Returns suggestions for review, not a sent reply, campaign, automation or price change. Context includes recent products; deals require marketing.view, and 30-day order aggregates/provided metrics require analytics.view. Support-only callers receive neither sales aggregates nor supplied dashboard metrics. range is a label, not a reporting date filter. Body flags cannot grant context access. A null draftId with persistenceWarning means persistence is unavailable. customer_message is also accepted for support drafts.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/operational-ai" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view plus workspace.view and all-products scope.", "x-request-fields": [ "productId: integer", "customerId: integer", "campaignId: integer", "customerMessage: string", "customer_message: string", "notes: string", "goal: string", "tone: string", "range: string", "metrics: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "dashboardContext: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOperationalAiRoutes.js", "services/operationalAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "customerId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "customerMessage": { "type": "string" }, "customer_message": { "type": "string" }, "notes": { "type": "string" }, "goal": { "type": "string" }, "tone": { "type": "string" }, "range": { "type": "string" }, "metrics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "dashboardContext": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/ai/operations/automation-recommendations": { "post": { "summary": "Draft automation recommendations", "description": "Requires configured operational AI availability and quota. Returns suggestions for review, not a sent reply, campaign, automation or price change. Context includes recent products; deals require marketing.view, and 30-day order aggregates/provided metrics require analytics.view. Support-only callers receive neither sales aggregates nor supplied dashboard metrics. range is a label, not a reporting date filter. Body flags cannot grant context access. A null draftId with persistenceWarning means persistence is unavailable. customer_message is also accepted for support drafts.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/operational-ai" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.manage plus workspace.view and all-products scope.", "x-request-fields": [ "productId: integer", "customerId: integer", "campaignId: integer", "customerMessage: string", "customer_message: string", "notes: string", "goal: string", "tone: string", "range: string", "metrics: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "dashboardContext: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOperationalAiRoutes.js", "services/operationalAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "customerId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "customerMessage": { "type": "string" }, "customer_message": { "type": "string" }, "notes": { "type": "string" }, "goal": { "type": "string" }, "tone": { "type": "string" }, "range": { "type": "string" }, "metrics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "dashboardContext": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/ai/operations/drafts": { "get": { "summary": "List the latest 50 permitted workspace operational drafts", "description": "Filters before LIMIT by support_reply:customers.view, analytics_summary:analytics.view, promotion_plan:marketing.view and automation_recommendation:marketing.manage, plus the analytics/marketing context permissions captured at generation. Legacy drafts with unknown context require both analytics.view and marketing.view as well as their tool permission. A caller with no eligible tools receives an empty list. Other workspaces are never included.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/operational-ai" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: drafts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "drafts": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "tool_type": { "type": "string" }, "generated_payload_json": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "workspace.view, all-products scope and each returned tool permission.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOperationalAiRoutes.js", "services/operationalAiService.js" ] } }, "/api/developer/ai/operations/drafts/{id}": { "delete": { "summary": "Mark an operational draft discarded", "description": "Soft status change to discarded, not physical record erasure or cancellation of previously executed work.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/operational-ai" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "tool_type": { "type": "string" }, "generated_payload_json": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "settings.manage, workspace.view, all-products scope and the permission for the stored tool type.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOperationalAiRoutes.js", "services/operationalAiService.js" ] } }, "/api/developer/ai/operations/drafts/{id}/apply": { "post": { "summary": "Mark an operational draft apply", "description": "Updates the stored draft review status only. Applying does not execute the suggested action or send anything. The stored context permissions must also be satisfied; legacy drafts with unknown context require analytics.view and marketing.view. Missing, foreign-workspace and unauthorized-tool/context drafts return 404 without modification.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/operational-ai" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "tool_type": { "type": "string" }, "generated_payload_json": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "settings.manage and all-products scope plus all-products scope and the permission for the stored tool type.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOperationalAiRoutes.js", "services/operationalAiService.js" ] } }, "/api/developer/ai/operations/drafts/{id}/dismiss": { "post": { "summary": "Mark an operational draft dismiss", "description": "Updates the stored draft review status only. Applying does not execute the suggested action or send anything. The stored context permissions must also be satisfied; legacy drafts with unknown context require analytics.view and marketing.view. Missing, foreign-workspace and unauthorized-tool/context drafts return 404 without modification.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/operational-ai" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "tool_type": { "type": "string" }, "generated_payload_json": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "workspace.view plus all-products scope and the permission for the stored tool type.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOperationalAiRoutes.js", "services/operationalAiService.js" ] } }, "/api/developer/ai/operations/drafts/{id}/save": { "post": { "summary": "Mark an operational draft save", "description": "Updates the stored draft review status only. Applying does not execute the suggested action or send anything. The stored context permissions must also be satisfied; legacy drafts with unknown context require analytics.view and marketing.view. Missing, foreign-workspace and unauthorized-tool/context drafts return 404 without modification.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/operational-ai" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "tool_type": { "type": "string" }, "generated_payload_json": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "workspace.view plus all-products scope and the permission for the stored tool type.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOperationalAiRoutes.js", "services/operationalAiService.js" ] } }, "/api/developer/ai/operations/promotion-plan": { "post": { "summary": "Draft a promotion plan", "description": "Requires configured operational AI availability and quota. Returns suggestions for review, not a sent reply, campaign, automation or price change. Context includes recent products; deals require marketing.view, and 30-day order aggregates/provided metrics require analytics.view. Support-only callers receive neither sales aggregates nor supplied dashboard metrics. range is a label, not a reporting date filter. Body flags cannot grant context access. A null draftId with persistenceWarning means persistence is unavailable. customer_message is also accepted for support drafts.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/operational-ai" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view plus workspace.view and all-products scope.", "x-request-fields": [ "productId: integer", "customerId: integer", "campaignId: integer", "customerMessage: string", "customer_message: string", "notes: string", "goal: string", "tone: string", "range: string", "metrics: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "dashboardContext: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOperationalAiRoutes.js", "services/operationalAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "customerId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "customerMessage": { "type": "string" }, "customer_message": { "type": "string" }, "notes": { "type": "string" }, "goal": { "type": "string" }, "tone": { "type": "string" }, "range": { "type": "string" }, "metrics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "dashboardContext": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/ai/operations/support-draft": { "post": { "summary": "Draft a customer support reply", "description": "Requires configured operational AI availability and quota. Returns suggestions for review, not a sent reply, campaign, automation or price change. Context includes recent products; deals require marketing.view, and 30-day order aggregates/provided metrics require analytics.view. Support-only callers receive neither sales aggregates nor supplied dashboard metrics. range is a label, not a reporting date filter. Body flags cannot grant context access. A null draftId with persistenceWarning means persistence is unavailable. customer_message is also accepted for support drafts.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/operational-ai" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.view plus workspace.view and all-products scope.", "x-request-fields": [ "productId: integer", "customerId: integer", "campaignId: integer", "customerMessage: string", "customer_message: string", "notes: string", "goal: string", "tone: string", "range: string", "metrics: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "dashboardContext: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOperationalAiRoutes.js", "services/operationalAiService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "customerId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "customerMessage": { "type": "string" }, "customer_message": { "type": "string" }, "notes": { "type": "string" }, "goal": { "type": "string" }, "tone": { "type": "string" }, "range": { "type": "string" }, "metrics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "dashboardContext": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "anyOf": [ { "required": [ "customerMessage" ] }, { "required": [ "customer_message" ] } ] } } } } } }, "/api/developer/analytics/activity": { "get": { "summary": "Read the product-scoped combined activity feed", "description": "Distinct from /revenue/activity and /developer/activity. Combines recorded website, plugin, email, download and usage events. Private customer/device diagnostics are not a public analytics feed; missing telemetry does not mean zero activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "source", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "customerId", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: range, start_date, end_date, currency, environment, limit, filters, summary, activity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "limit": { "type": "integer" }, "filters": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "activity": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and assigned-product scope.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer", "query source: string", "query type: string", "query search: string", "query customerId: string", "query limit: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueAnalyticsRoutes.js", "services/developerActivityService.js" ] } }, "/api/developer/analytics/overview": { "get": { "summary": "Fetch developer analytics overview.", "description": "Keep date, product, currency and live/test scope aligned. Missing measurements are not certified zeroes; imported external amounts are not automatically funded managed-sale earnings. Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/analytics" }, "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom start; start/from aliases are accepted." }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom end; end/to aliases are accepted." }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "includeResellers", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "" }, { "name": "tab", "in": "query", "schema": { "type": "string", "enum": [ "overview", "commerce", "products", "customers", "marketing", "engagement", "retention", "technical" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "Revenue, product, customer, activation, download, subscription, marketplace, promotion, and export-ready summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dateRange": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "comparisonRange": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currency": { "type": "string" }, "environment": { "type": "string" }, "activeTab": { "type": "string" }, "availableTabs": { "type": "array", "items": { "type": "string" } }, "productFilter": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "unavailableSections": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "kpis": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentMonthCharges": { "type": "object", "properties": { "range": { "type": "string" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "monthly_minimum_cents": { "type": "integer", "minimum": 0 }, "platform_fees_from_direct_sales_cents": { "type": "integer", "minimum": 0 }, "marketplace_fees_cents": { "type": "integer", "minimum": 0 }, "marketing_email_charges_cents": { "type": "integer", "minimum": 0 }, "redemption_overage_charges_cents": { "type": "integer", "minimum": 0 }, "minimum_adjustment_cents": { "type": "integer", "minimum": 0 }, "pre_minimum_total_cents": { "type": "integer", "minimum": 0 }, "billable_activity_cents": { "type": "integer", "minimum": 0 }, "current_total_if_billed_today_cents": { "type": "integer", "minimum": 0 }, "external_redemptions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "marketing_emails": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true }, "includeResellerSales": { "type": "boolean" }, "resellerDataUnavailable": { "type": "boolean" }, "resellerEstimatesIncomplete": { "type": "boolean" }, "topProducts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "revenueCents": { "type": "integer" }, "orders": { "type": "integer" } }, "additionalProperties": true } }, "recentActivity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "engagementSummary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "customerGeography": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "revenueTimeSeries": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "trafficOverview": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "retentionSummary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "technicalHealth": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "customerBehavior": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "insights": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "raw": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query range: string", "query startDate: string. Custom start; start/from aliases are accepted.", "query endDate: string. Custom end; end/to aliases are accepted.", "query productId: integer", "query currency: string", "query environment: string", "query includeResellers: boolean", "query tab: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueAnalyticsRoutes.js", "controllers/developerRevenueController.js", "services/developerAnalyticsOverviewService.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/analytics/overview/export.csv": { "get": { "summary": "Export analytics overview CSV.", "description": "Keep date, product, currency and live/test scope aligned. Missing measurements are not certified zeroes; imported external amounts are not automatically funded managed-sale earnings. Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/analytics" }, "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom start; start/from aliases are accepted." }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom end; end/to aliases are accepted." }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "includeResellers", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "" }, { "name": "tab", "in": "query", "schema": { "type": "string", "enum": [ "overview", "commerce", "products", "customers", "marketing", "engagement", "retention", "technical" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "CSV file.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query range: string", "query startDate: string. Custom start; start/from aliases are accepted.", "query endDate: string. Custom end; end/to aliases are accepted.", "query productId: integer", "query currency: string", "query environment: string", "query includeResellers: boolean", "query tab: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueAnalyticsRoutes.js", "controllers/developerRevenueController.js", "services/developerAnalyticsOverviewService.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/analytics/revenue/activity": { "get": { "summary": "Fetch revenue activity timeline.", "description": "Keep date, product, currency and live/test scope aligned. Missing measurements are not certified zeroes; imported external amounts are not automatically funded managed-sale earnings. Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/analytics" }, "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom start; start/from aliases are accepted." }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom end; end/to aliases are accepted." }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "includeResellers", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "" }, { "name": "tab", "in": "query", "schema": { "type": "string", "enum": [ "overview", "commerce", "products", "customers", "marketing", "engagement", "retention", "technical" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "Activity rows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "limit": { "type": "integer" }, "activity": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "source": { "type": "string" }, "source_id": { "type": "integer", "minimum": 1 }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "amount_cents": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "product": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "backend_gaps": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query range: string", "query startDate: string. Custom start; start/from aliases are accepted.", "query endDate: string. Custom end; end/to aliases are accepted.", "query productId: integer", "query currency: string", "query environment: string", "query includeResellers: boolean", "query tab: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueAnalyticsRoutes.js", "controllers/developerRevenueController.js", "services/developerAnalyticsOverviewService.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/analytics/revenue/current-month-charges": { "get": { "summary": "Fetch current month charge summary.", "description": "Keep date, product, currency and live/test scope aligned. Missing measurements are not certified zeroes; imported external amounts are not automatically funded managed-sale earnings. Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/analytics" }, "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom start; start/from aliases are accepted." }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom end; end/to aliases are accepted." }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "includeResellers", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "" }, { "name": "tab", "in": "query", "schema": { "type": "string", "enum": [ "overview", "commerce", "products", "customers", "marketing", "engagement", "retention", "technical" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "Current charge summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "charges": { "type": "object", "properties": { "range": { "type": "string" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "monthly_minimum_cents": { "type": "integer", "minimum": 0 }, "platform_fees_from_direct_sales_cents": { "type": "integer", "minimum": 0 }, "marketplace_fees_cents": { "type": "integer", "minimum": 0 }, "marketing_email_charges_cents": { "type": "integer", "minimum": 0 }, "redemption_overage_charges_cents": { "type": "integer", "minimum": 0 }, "minimum_adjustment_cents": { "type": "integer", "minimum": 0 }, "pre_minimum_total_cents": { "type": "integer", "minimum": 0 }, "billable_activity_cents": { "type": "integer", "minimum": 0 }, "current_total_if_billed_today_cents": { "type": "integer", "minimum": 0 }, "external_redemptions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "marketing_emails": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query range: string", "query startDate: string. Custom start; start/from aliases are accepted.", "query endDate: string. Custom end; end/to aliases are accepted.", "query productId: integer", "query currency: string", "query environment: string", "query includeResellers: boolean", "query tab: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueAnalyticsRoutes.js", "controllers/developerRevenueController.js", "services/developerAnalyticsOverviewService.js", "services/developerRevenueReportingService.js", "services/developerBillingChargeService.js" ] } }, "/api/developer/analytics/revenue/products": { "get": { "summary": "Fetch product revenue performance.", "description": "Keep date, product, currency and live/test scope aligned. Missing measurements are not certified zeroes; imported external amounts are not automatically funded managed-sale earnings. Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/analytics" }, "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom start; start/from aliases are accepted." }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom end; end/to aliases are accepted." }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "includeResellers", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "" }, { "name": "tab", "in": "query", "schema": { "type": "string", "enum": [ "overview", "commerce", "products", "customers", "marketing", "engagement", "retention", "technical" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "Product revenue rows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "sort": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "gross_revenue_cents": { "type": "integer" }, "net_revenue_cents": { "type": "integer" }, "estimated_net_revenue_cents": { "type": "integer" }, "order_count": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query range: string", "query startDate: string. Custom start; start/from aliases are accepted.", "query endDate: string. Custom end; end/to aliases are accepted.", "query productId: integer", "query currency: string", "query environment: string", "query includeResellers: boolean", "query tab: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueAnalyticsRoutes.js", "controllers/developerRevenueController.js", "services/developerAnalyticsOverviewService.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/analytics/revenue/summary": { "get": { "summary": "Fetch revenue summary.", "description": "Keep date, product, currency and live/test scope aligned. Missing measurements are not certified zeroes; imported external amounts are not automatically funded managed-sale earnings. Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/analytics" }, "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom start; start/from aliases are accepted." }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Custom end; end/to aliases are accepted." }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "includeResellers", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "" }, { "name": "tab", "in": "query", "schema": { "type": "string", "enum": [ "overview", "commerce", "products", "customers", "marketing", "engagement", "retention", "technical" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "Revenue summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "environment": { "type": "string" }, "summary": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "gross_revenue_cents": { "type": "integer" }, "net_revenue_cents": { "type": "integer" }, "total_orders": { "type": "integer" }, "developer_earnings_cents": { "type": "integer" }, "platform_fees_cents": { "type": "integer" }, "marketplace_fees_cents": { "type": "integer" }, "refund_total_cents": { "type": "integer" }, "chargeback_total_cents": { "type": "integer" }, "disputed_total_cents": { "type": "integer" }, "affiliate_share_cents": { "type": "integer" }, "collaborator_share_cents": { "type": "integer" }, "partner_processing_fee_cents": { "type": "integer" }, "estimated_net_revenue_cents": { "type": "integer" }, "unique_customers": { "type": "integer" }, "subscription_metrics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "revenue_breakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "products": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "timeline": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "windows": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "unavailable_sections": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "dashboard_metrics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "current_month_charges": { "type": "object", "properties": { "range": { "type": "string" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "monthly_minimum_cents": { "type": "integer", "minimum": 0 }, "platform_fees_from_direct_sales_cents": { "type": "integer", "minimum": 0 }, "marketplace_fees_cents": { "type": "integer", "minimum": 0 }, "marketing_email_charges_cents": { "type": "integer", "minimum": 0 }, "redemption_overage_charges_cents": { "type": "integer", "minimum": 0 }, "minimum_adjustment_cents": { "type": "integer", "minimum": 0 }, "pre_minimum_total_cents": { "type": "integer", "minimum": 0 }, "billable_activity_cents": { "type": "integer", "minimum": 0 }, "current_total_if_billed_today_cents": { "type": "integer", "minimum": 0 }, "external_redemptions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "marketing_emails": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true }, "activity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "email_marketing": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "subscription_analytics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "calculation_rules": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query range: string", "query startDate: string. Custom start; start/from aliases are accepted.", "query endDate: string. Custom end; end/to aliases are accepted.", "query productId: integer", "query currency: string", "query environment: string", "query includeResellers: boolean", "query tab: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueAnalyticsRoutes.js", "controllers/developerRevenueController.js", "services/developerAnalyticsOverviewService.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/billing/invoices": { "get": { "summary": "List developer billing invoices.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "invoices[].", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "statement_id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string" }, "provider_invoice_id": { "type": [ "string", "null" ] }, "display_number": { "type": "string" }, "provider_label": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": "integer", "minimum": 0 }, "statement_period_start": { "type": [ "string", "null" ], "format": "date-time" }, "statement_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "collection_attempts": { "type": "integer" }, "hosted_invoice_url": { "type": [ "string", "null" ] }, "invoice_pdf": { "type": [ "string", "null" ] }, "line_item_summary": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBillingCollectionRoutes.js", "services/developerBillingCollectionService.js" ] } }, "/api/developer/billing/invoices/{invoiceId}": { "get": { "summary": "Fetch developer billing invoice.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ invoice }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "statement_id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string" }, "provider_invoice_id": { "type": [ "string", "null" ] }, "display_number": { "type": "string" }, "provider_label": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": "integer", "minimum": 0 }, "statement_period_start": { "type": [ "string", "null" ], "format": "date-time" }, "statement_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "collection_attempts": { "type": "integer" }, "hosted_invoice_url": { "type": [ "string", "null" ] }, "invoice_pdf": { "type": [ "string", "null" ] }, "line_item_summary": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBillingCollectionRoutes.js", "services/developerBillingCollectionService.js" ] } }, "/api/developer/billing/invoices/{invoiceId}/download.csv": { "get": { "summary": "Download the developer billing invoice CSV", "description": "Requires billing.view and all-products scope. Downloads the owned developer-billing invoice as CSV, not a customer purchase invoice or payment receipt. Read Content-Disposition for the filename. Returns 404 BILLING_INVOICE_NOT_FOUND for an unavailable invoice.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBillingCollectionRoutes.js", "services/developerBillingCollectionService.js" ] } }, "/api/developer/billing/payment-method": { "get": { "summary": "Fetch saved developer billing payment method preview.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [], "responses": { "200": { "description": "{ payment_method }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_method": { "type": "object", "properties": { "payment_method": { "type": "object", "properties": { "brand": { "type": "string" }, "last4": { "type": "string" }, "exp_month": { "type": "integer" }, "exp_year": { "type": "integer" } }, "additionalProperties": true }, "provider": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBillingCollectionRoutes.js", "services/developerBillingCollectionService.js" ] } }, "/api/developer/billing/portal-session": { "post": { "summary": "Create Stripe billing portal session.", "description": "Requires billing.view + billing.manage and all-products workspace scope because the portal can edit payment methods and billing contact information. billing.view alone permits reports, not portal session creation; missing management permission returns 403 developer_team_permission_denied. Return URL is constructed by the application. This developer-billing portal is not the customer subscription invoice-history portal, Stripe Connect onboarding or a payout request. Side effects: Creates Stripe Billing Portal session.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [], "responses": { "200": { "description": "Portal session URL/metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "provider": { "type": "string" }, "stripe_mode": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view + billing.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBillingCollectionRoutes.js", "services/developerBillingCollectionService.js" ] } }, "/api/developer/billing/statements": { "get": { "summary": "List developer billing statements.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "statements[].", "content": { "application/json": { "schema": { "type": "object", "properties": { "statements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "currency": { "type": "string" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "total_cents": { "type": "integer", "minimum": 0 }, "platform_fee_cents": { "type": "integer", "minimum": 0 }, "marketplace_fee_cents": { "type": "integer", "minimum": 0 }, "marketing_email_usage_cents": { "type": "integer", "minimum": 0 }, "marketing_email_usage_quantity": { "type": "integer" }, "marketing_email_included_quantity": { "type": "integer" }, "marketing_email_billable_quantity": { "type": "integer" }, "external_redemption_usage_cents": { "type": "integer", "minimum": 0 }, "external_redemption_usage_quantity": { "type": "integer" }, "external_redemption_included_quantity": { "type": "integer" }, "external_redemption_billable_quantity": { "type": "integer" }, "minimum_adjustment_cents": { "type": "integer", "minimum": 0 }, "line_item_summary": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "invoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "statement_id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string" }, "provider_invoice_id": { "type": [ "string", "null" ] }, "display_number": { "type": "string" }, "provider_label": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": "integer", "minimum": 0 }, "statement_period_start": { "type": [ "string", "null" ], "format": "date-time" }, "statement_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "collection_attempts": { "type": "integer" }, "hosted_invoice_url": { "type": [ "string", "null" ] }, "invoice_pdf": { "type": [ "string", "null" ] }, "line_item_summary": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBillingCollectionRoutes.js", "services/developerBillingCollectionService.js" ] } }, "/api/developer/billing/statements/{statementId}/download.csv": { "get": { "summary": "Download the developer billing statement CSV", "description": "Requires billing.view and all-products scope. Downloads the owned monthly billing statement as CSV, not a payout execution or confirmation of bank receipt. Read Content-Disposition for the filename. Returns 404 BILLING_STATEMENT_NOT_FOUND for an unavailable statement.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "statementId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBillingCollectionRoutes.js", "services/developerBillingCollectionService.js" ] } }, "/api/developer/billing/statements/{statementId}/invoice": { "get": { "summary": "Fetch invoice for a statement.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "statementId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ invoice }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "statement_id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string" }, "provider_invoice_id": { "type": [ "string", "null" ] }, "display_number": { "type": "string" }, "provider_label": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": "integer", "minimum": 0 }, "statement_period_start": { "type": [ "string", "null" ], "format": "date-time" }, "statement_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "collection_attempts": { "type": "integer" }, "hosted_invoice_url": { "type": [ "string", "null" ] }, "invoice_pdf": { "type": [ "string", "null" ] }, "line_item_summary": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBillingCollectionRoutes.js", "services/developerBillingCollectionService.js" ] } }, "/api/developer/billing/status": { "get": { "summary": "Fetch developer billing status and billing gate.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [], "responses": { "200": { "description": "{ status } including billing_gate/billingGate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "developer_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "billing_good_standing": { "type": "boolean" }, "amount_due_cents": { "type": "integer", "minimum": 0 }, "outstanding_non_sale_charges_cents": { "type": "integer", "minimum": 0 }, "invoice_balance_cents": { "type": "integer", "minimum": 0 }, "projected_minimum_adjustment_cents": { "type": "integer", "minimum": 0 }, "billing_gate": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "billingGate": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBillingCollectionRoutes.js", "services/developerBillingCollectionService.js" ] } }, "/api/developer/brand/domain": { "get": { "summary": "Fetch smart/manual brand-domain state.", "description": "domains.view and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard. Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [], "responses": { "200": { "description": "current step, provider, required DNS records, events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js" ] } }, "/api/developer/brand/domain/advance": { "post": { "summary": "Advance to the next incomplete DNS setup step", "description": "domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ] } }, "/api/developer/brand/domain/check": { "post": { "summary": "Check the required DNS records", "description": "Checks required or non-skipped records and writes observed results. The eight-second cooldown returns 429 DNS_CHECK_COOLDOWN. If the saved setup changes during checking, 409 DNS_SETUP_CHANGED requires reloading the current setup before retrying. HTTP success is not proof that every record or SSL certificate is ready. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "BRAND_DOMAIN_NOT_FOUND", "DNS_CHECK_COOLDOWN", "DNS_SETUP_CHANGED", "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ] } }, "/api/developer/brand/domain/check-step": { "post": { "summary": "Check one DNS setup step.", "description": "step_key aliases stepKey. A nonempty key checks only that record; omission or an empty key checks all required or non-skipped records, not only currentStep. This writes observed results and can refresh providers. An eight-second check cooldown returns 429 DNS_CHECK_COOLDOWN. A changed setup returns 409 DNS_SETUP_CHANGED: reload before retrying. An unknown nonempty key returns 404 DNS_STEP_NOT_FOUND. HTTP success is not verification proof. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard. Side effects: Changes or processes the authorized resource: Check one DNS setup step.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [], "responses": { "200": { "description": "step verification result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [ "stepKey: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "BRAND_DOMAIN_NOT_FOUND", "DNS_STEP_NOT_FOUND", "DNS_CHECK_COOLDOWN", "DNS_SETUP_CHANGED", "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "stepKey": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/brand/domain/email-identity": { "post": { "summary": "Save domain-linked sender identity", "description": "Flat and email_identity forms and supported snake_case fields are accepted. This saves identity, not sending-domain verification or permission to send. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [ "emailIdentity: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailIdentity": { "type": "object", "properties": { "defaultSenderName": { "type": "string" }, "replyToEmail": { "type": "string", "format": "email" }, "supportEmail": { "type": "string", "format": "email" }, "marketingSenderEmail": { "type": "string", "format": "email" }, "transactionalSenderEmail": { "type": "string", "format": "email" }, "emailFooterText": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } } } }, "/api/developer/brand/domain/email-providers": { "post": { "summary": "Connect or refresh the domain with email providers", "description": "Requires domains.view, domains.manage and all-products workspace scope. No request body fields are read. Creates a missing sending-domain registration or refreshes the existing one, then returns wizard state. Read providerVerification and readiness for transactional, marketing and secure tracking status; HTTP 200 is not activation or delivery proof. Provider failures can return an operation error. Does not change incoming mailbox hosting or registrar DNS. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "BRAND_DOMAIN_NOT_FOUND", "DEVELOPER_BRAND_DOMAIN_ERROR", "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ] } }, "/api/developer/brand/domain/events": { "get": { "summary": "Read the domain setup event history", "description": "domains.view and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "event_type": { "type": "string" }, "message": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ] } }, "/api/developer/brand/domain/prepare": { "post": { "summary": "Prepare provider records and verify domain readiness", "description": "Requires domains.view, domains.manage and all-products workspace scope. Starts or refreshes hosting/email provider registration and verification; this is a write, not a health probe. retry:true forces preparation; otherwise a recent attempt can return current state during the 30-second preparation cooldown. Concurrent preparation is serialized. Inspect currentStep, needsPreparation, provider errors and readiness; HTTP 200 can still mean incomplete setup. No DNS-provider records are edited by this call. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [ "retry: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "BRAND_DOMAIN_NOT_FOUND", "DEVELOPER_BRAND_DOMAIN_ERROR", "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "retry": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/brand/domain/provider": { "post": { "summary": "Choose the DNS provider instructions", "description": "Send provider (providerKey/provider_key are aliases). Does not grant provider-account access or automate arbitrary DNS changes. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [ "provider: string", "providerKey: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "providerKey": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/brand/domain/reset": { "post": { "summary": "Reset the domain setup progress", "description": "Resets setup_status/current_step_key. It does not delete DNS records at the provider or guarantee removal of an existing domain or SSL certificate. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ] } }, "/api/developer/brand/domain/sender-profiles": { "post": { "summary": "Save sender local parts for the active sending domain", "description": "At least one supported purpose is required; flat purpose fields and local_part aliases are accepted. Requires an active custom sending domain. Saving does not bypass sender verification. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [ "senderProfiles: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "senderProfiles": { "type": "object", "properties": { "licensing": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "additionalProperties": true } ] }, "notifications": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "additionalProperties": true } ] }, "marketing": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "additionalProperties": true } ] } }, "additionalProperties": true } }, "additionalProperties": true } } } } } }, "/api/developer/brand/domain/skip-step": { "post": { "summary": "Skip a genuinely optional DNS step", "description": "step_key aliases stepKey. Required records cannot be skipped; DNS_STEP_REQUIRED is a failure, not a successful connection. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [ "stepKey: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stepKey": { "type": "string" } }, "required": [ "stepKey" ], "additionalProperties": true } } } } } }, "/api/developer/brand/domain/start": { "post": { "summary": "Start smart/manual DNS workflow.", "description": "root_domain/domain alias rootDomain; storefront_subdomain/storefrontHost/storefront_host alias storefrontSubdomain. Omit the storefront subdomain or use @ for the root domain. DNS provider detection is automatic, not an input to this call. Readiness, DNS and SSL are verified separately. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard. Side effects: Creates or initializes brand domain workflow.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [], "responses": { "201": { "description": "201 domain workflow state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [ "rootDomain: string (required)", "storefrontSubdomain: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" } }, "required": [ "rootDomain" ], "additionalProperties": true } } } } } }, "/api/developer/brand/domain/storefront-provider": { "post": { "summary": "Connect or refresh the storefront hosting provider", "description": "Requires domains.view, domains.manage and all-products workspace scope. No request body fields are read. Registers a missing saved apex/subdomain with hosting or refreshes its existing connection. Routing verification and active SSL are separate readiness requirements; inspect currentStep and readiness.storefront. HTTP 200 alone does not prove the connection is ready. This write does not edit registrar DNS or promise certificate timing. domains.view + domains.manage and all-products workspace scope. Selected-product teammates cannot use this workspace-wide domain wizard.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, providerDetection, currentStep, current_step, wizardProgress, records, featureSummaries, events, allRequiredVerified, providerSupport, branding, storefrontDomain, emailDomains, emailDomainSettings, needsPreparation, automaticProviderSetup, emailProvidersConfigured, emailProvidersReady, providerPreparation, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" }, "rootDomain": { "type": "string" }, "storefrontSubdomain": { "type": "string" }, "setupStatus": { "type": "string" }, "currentStepKey": { "type": "string" } }, "additionalProperties": true }, "providerDetection": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "currentStep": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "current_step": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "wizardProgress": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "totalCount": { "type": "integer" } }, "additionalProperties": true } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "featureSummaries": { "type": "array", "items": { "type": "object", "properties": { "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "completeCount": { "type": "integer" }, "requiredCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerDomainId": { "type": [ "integer", "null" ] }, "stepKey": { "type": "string" }, "step_key": { "type": "string" }, "featureKey": { "type": "string" }, "feature_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "warning": { "type": "string" }, "purpose": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" }, "action": { "type": "string", "description": "Non-DNS step: prepare-domains, storefront-provider, email-providers or email-identity. Do not add it as a DNS row." }, "type": { "type": "string", "description": "DNS type returned by the provider, such as A, CNAME, TXT or MX; absent on action steps." }, "host": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "integer" ] }, "priority": { "type": "integer", "description": "MX priority, entered separately from exchange." }, "exchange": { "type": "string" }, "copyBlocked": { "type": "boolean", "description": "Missing provider value cannot be copied. Also respect copyPlan.mode=blocked." }, "copyPlan": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "create", "replace", "preserve", "blocked" ] }, "value": { "type": "string" }, "previousValue": { "type": "string" }, "message": { "type": "string" } }, "required": [ "mode" ], "additionalProperties": true, "description": "Use value for create/replace, keep existing policy for preserve, and resolve message before copying for blocked." }, "errorMessage": { "type": "string" }, "error_message": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "allRequiredVerified": { "type": "boolean" }, "providerSupport": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "storefrontDomain": { "type": "string" }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "needsPreparation": { "type": "boolean" }, "automaticProviderSetup": { "type": "boolean" }, "emailProvidersConfigured": { "type": "boolean" }, "emailProvidersReady": { "type": "boolean" }, "providerPreparation": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missingRecords": { "type": "array", "items": { "type": "string" } }, "errorMessage": { "type": "string" } }, "additionalProperties": true }, "readiness": { "type": "object", "properties": { "dns": { "type": "boolean" }, "storefront": { "type": "boolean" }, "email": { "type": "boolean" }, "tracking": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "senders": { "type": "boolean" }, "identity": { "type": "boolean" }, "providersConfigured": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view + domains.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "BRAND_DOMAIN_NOT_FOUND", "DEVELOPER_BRAND_DOMAIN_ERROR", "developer_team_permission_denied", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerBrandDomainRoutes.js", "services/developerBrandDomainService.js", "services/developerEmailDomainService.js", "services/developerStorefrontDomainService.js", "services/brandDomainReadiness.js" ] } }, "/api/developer/branding": { "get": { "summary": "Fetch Brand Manager payload.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [], "responses": { "200": { "description": "branding, publicBranding, storefrontDomain, emailDomains, linkValidation, domainDocs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "publicBranding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "storefrontDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" } }, "additionalProperties": true }, "storefrontDomainSettings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "linkValidation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainDocs": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "services/brandingWorkspaceService.js" ] }, "put": { "summary": "Update Brand Manager fields.", "description": "Workspace-wide branding save requires brand.manage and all-products scope. Prefer versioned section saves for Identity, Visuals and Support. Side effects: Writes developer branding.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [], "responses": { "200": { "description": "updated branding payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "publicBranding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "storefrontDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" } }, "additionalProperties": true }, "storefrontDomainSettings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "linkValidation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainDocs": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "storeName: string", "developerDisplayName: string", "tagline: string", "slug: string", "shortDescription: string", "marketplaceBio: string", "logos: object", "colors: object", "support: object", "emailIdentity: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "socialLinks: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "domains: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "services/brandingWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/branding/custom-domain": { "post": { "summary": "Start/connect storefront custom domain from Brand Manager.", "description": "Uses the current saved custom domain when omitted. Supply a hostname, not DNS-provider credentials. DNS propagation and SSL provisioning are asynchronous. Side effects: Creates storefront domain row and updates branding domain status.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [], "responses": { "201": { "description": "201 branding payload with storefrontDomainResult.", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "publicBranding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "storefrontDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" } }, "additionalProperties": true }, "storefrontDomainSettings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "linkValidation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainDocs": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "storefrontDomainResult": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "domain: string", "customDomain: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "services/brandingWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "customDomain": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/branding/dark-logo": { "post": { "summary": "Upload the brand dark-logo", "description": "Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-assets" }, "parameters": [ { "name": "draft", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "required": false, "description": "" } ], "responses": { "201": { "description": "HTTP 201: url, key, draft, branding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "key": { "type": "string" }, "draft": { "type": "boolean" }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "The supplied media or file type is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "brand.manage and all-products scope.", "x-request-fields": [ "query draft: string", "file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "middleware/uploadGuards.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/developer/branding/default-product-image": { "post": { "summary": "Upload the brand default-product-image", "description": "Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-assets" }, "parameters": [ { "name": "draft", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "required": false, "description": "" } ], "responses": { "201": { "description": "HTTP 201: url, key, draft, branding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "key": { "type": "string" }, "draft": { "type": "boolean" }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "The supplied media or file type is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "brand.manage and all-products scope.", "x-request-fields": [ "query draft: string", "file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "middleware/uploadGuards.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/developer/branding/email-domain": { "post": { "summary": "Start/connect email sending domain from Brand Manager.", "description": "Email-sending DNS verification is separate from storefront SSL. Side effects: Creates email domain row and updates branding sending-domain status.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [], "responses": { "201": { "description": "201 branding payload with emailDomainResult.", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "publicBranding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "storefrontDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" } }, "additionalProperties": true }, "storefrontDomainSettings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "emailDomains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "emailDomainSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "linkValidation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainDocs": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "emailDomainResult": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "domain: string", "sendingDomain: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "services/brandingWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "sendingDomain": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/branding/icon": { "post": { "summary": "Upload the brand icon", "description": "Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-assets" }, "parameters": [ { "name": "draft", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "required": false, "description": "" } ], "responses": { "201": { "description": "HTTP 201: url, key, draft, branding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "key": { "type": "string" }, "draft": { "type": "boolean" }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "The supplied media or file type is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "brand.manage and all-products scope.", "x-request-fields": [ "query draft: string", "file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "middleware/uploadGuards.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/developer/branding/light-logo": { "post": { "summary": "Upload the brand light-logo", "description": "Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-assets" }, "parameters": [ { "name": "draft", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "required": false, "description": "" } ], "responses": { "201": { "description": "HTTP 201: url, key, draft, branding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "key": { "type": "string" }, "draft": { "type": "boolean" }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "The supplied media or file type is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "brand.manage and all-products scope.", "x-request-fields": [ "query draft: string", "file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "middleware/uploadGuards.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/developer/branding/links/validate": { "get": { "summary": "Inspect configured branding links", "description": "Checks required configured values, not remote HTTP availability. Optional missing values can still report ok:true. It is not proof that every external page is reachable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-assets" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: ok, checks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": [ "string", "null" ] }, "ok": { "type": "boolean" }, "required": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "brand.view.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "middleware/uploadGuards.js" ] } }, "/api/developer/branding/logo": { "post": { "summary": "Upload the brand logo", "description": "Send one file field. JPEG, PNG, WebP and GIF extensions and matching accepted MIME types are supported; SVG is rejected. Default limit 10 MiB, subject to configured image limit. Upload creates a public asset; never upload private customer records. draft=1 returns url/key/draft:true without changing branding; otherwise returns updated branding. Storage configuration is required.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-assets" }, "parameters": [ { "name": "draft", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "required": false, "description": "" } ], "responses": { "201": { "description": "HTTP 201: url, key, draft, branding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "key": { "type": "string" }, "draft": { "type": "boolean" }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "The supplied media or file type is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "brand.manage and all-products scope.", "x-request-fields": [ "query draft: string", "file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "middleware/uploadGuards.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/developer/branding/test-email": { "post": { "summary": "Send a branded transactional-email test", "description": "Send email or to. Actually sends to that address using the resolved notifications sender; it is not a marketing campaign, subscription or proof of domain readiness. Requires configured email transport; success does not guarantee inbox delivery.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-assets" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: ok, email.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "email": { "type": "string", "format": "email" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "brand.manage and all-products scope.", "x-request-fields": [ "email: string", "to: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "middleware/uploadGuards.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "to": { "type": "string", "format": "email" } }, "additionalProperties": true } } } } } }, "/api/developer/branding/verify-domain": { "post": { "summary": "Refresh the connected storefront domain", "description": "Compatibility refresh workflow for the connected storefront domain. Website refresh selects the current website domain; email refresh selects the first returned sending domain. Prefer the guided domain API for explicit setup progress. Performs external checks and synchronizes branding. HTTP 200 does not mean DNS/SSL or email authentication is ready.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-assets" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: branding, publicBranding, storefrontDomainResult.", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "publicBranding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "storefrontDomainResult": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.manage and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "middleware/uploadGuards.js", "services/developerStorefrontDomainService.js", "services/developerEmailDomainService.js" ] } }, "/api/developer/branding/verify-email-domain": { "post": { "summary": "Refresh the connected sending domain", "description": "Compatibility refresh workflow for the connected sending domain. Website refresh selects the current website domain; email refresh selects the first returned sending domain. Prefer the guided domain API for explicit setup progress. Performs external checks and synchronizes branding. HTTP 200 does not mean DNS/SSL or email authentication is ready.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-assets" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: branding, publicBranding, emailDomainResult.", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "publicBranding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "emailDomainResult": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.manage and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "middleware/uploadGuards.js", "services/developerStorefrontDomainService.js", "services/developerEmailDomainService.js" ] } }, "/api/developer/branding/workspace/{section}": { "get": { "summary": "Read the current section", "description": "section is identity, visuals or support. Support also requires customers.view. Private contact-form delivery addresses must not be published.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-workspaces" }, "parameters": [ { "name": "section", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "branding, supportCenter (for support), version, uploadMaxBytes, and canManage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "supportCenter": { "type": [ "object", "null" ], "properties": { "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "type": { "type": "string" }, "visible": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true }, "version": { "type": "string" }, "uploadMaxBytes": { "type": "integer" }, "canManage": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "services/brandingWorkspaceService.js" ] }, "put": { "summary": "Save the reviewed section version", "description": "Read the section first and send its exact version. A stale version returns 409 BRANDING_EDIT_CONFLICT. identity accepts identity fields; visuals accepts logos/colors; support accepts contact settings, articles and links. Articles are the complete edited list; published answers need body content. applyFields is section-specific, not an arbitrary property list.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-workspaces" }, "parameters": [ { "name": "section", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated branding/supportCenter/version; stale input returns 409 BRANDING_EDIT_CONFLICT.", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "supportCenter": { "type": [ "object", "null" ], "properties": { "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "type": { "type": "string" }, "visible": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true }, "version": { "type": "string" }, "uploadMaxBytes": { "type": "integer" }, "canManage": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "version: string (required)", "values: object (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "BRANDING_EDIT_CONFLICT" ], "x-source-files": [ "routes/developerBrandingRoutes.js", "services/developerBrandingService.js", "services/brandingWorkspaceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "values": { "type": "object", "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "applyFields": { "type": "array", "items": { "type": "string" } }, "supportEmail": { "type": "string" }, "supportDisplayName": { "type": "string" }, "businessAddress": { "type": "string" }, "supportPhone": { "type": "string" }, "primaryContactName": { "type": "string" }, "supportContactLabel": { "type": "string" }, "responseTimeMessage": { "type": "string" }, "availabilityMessage": { "type": "string" }, "contactFormEnabled": { "type": "boolean" }, "contactFormDestinationEmail": { "type": "string", "format": "email" }, "supportPageEnabled": { "type": "boolean" }, "supportContactDetails": { "type": "boolean" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "type": { "type": "string" }, "visible": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "additionalProperties": true } }, "links": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } }, "required": [ "version", "values" ], "additionalProperties": true } } } } } }, "/api/developer/catalog-imports": { "get": { "summary": "List the latest workspace import jobs", "description": "Returns the latest 10 workspace jobs. Import access requires the appropriate create/edit scope.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [], "responses": { "200": { "description": "{ jobs: [...] }; current list is limited to the latest 10 jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "storeUrl": { "type": "string" }, "mode": { "type": "string" }, "targetId": { "type": [ "integer", "null" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "existingProductId": { "type": [ "integer", "null" ] }, "existingPublished": { "type": "boolean" }, "matchConflict": { "type": "boolean" } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "progress": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pendingPages": { "type": "integer" }, "minimumPaidPriceCents": { "type": "integer", "minimum": 0 }, "export": { "type": [ "object", "null" ], "properties": { "filename": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "rowCount": { "type": "integer" }, "sample": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] }, "post": { "summary": "Start an import", "description": "export is one CSV/TSV/XLSX/JSON multipart file up to 8 MB. Use a public authorized source URL or export. Imported products remain drafts; do not copy accounts, billing authority or consent implicitly.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [], "responses": { "201": { "description": "201 with the visible job and current status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "storeUrl": { "type": "string" }, "mode": { "type": "string" }, "targetId": { "type": [ "integer", "null" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "existingProductId": { "type": [ "integer", "null" ] }, "existingPublished": { "type": "boolean" }, "matchConflict": { "type": "boolean" } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "progress": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pendingPages": { "type": "integer" }, "minimumPaidPriceCents": { "type": "integer", "minimum": 0 }, "export": { "type": [ "object", "null" ], "properties": { "filename": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "rowCount": { "type": "integer" }, "sample": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "storeUrl: string", "mode: catalog | single", "targetId: integer", "export: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeUrl": { "type": "string" }, "mode": { "type": "string", "enum": [ "catalog", "single" ] }, "targetId": { "type": "integer", "minimum": 1 }, "export": { "type": "string", "format": "binary" } }, "additionalProperties": true, "anyOf": [ { "required": [ "storeUrl" ] }, { "required": [ "export" ] } ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "storeUrl": { "type": "string" }, "mode": { "type": "string", "enum": [ "catalog", "single" ] }, "targetId": { "type": "integer", "minimum": 1 }, "export": { "type": "string", "format": "binary" } }, "additionalProperties": true, "anyOf": [ { "required": [ "storeUrl" ] }, { "required": [ "export" ] } ] } } } } } }, "/api/developer/catalog-imports/{id}": { "get": { "summary": "Read a workspace-owned job", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Visible job, candidates, warnings, progress, and permitted results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "storeUrl": { "type": "string" }, "mode": { "type": "string" }, "targetId": { "type": [ "integer", "null" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "existingProductId": { "type": [ "integer", "null" ] }, "existingPublished": { "type": "boolean" }, "matchConflict": { "type": "boolean" } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "progress": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pendingPages": { "type": "integer" }, "minimumPaidPriceCents": { "type": "integer", "minimum": 0 }, "export": { "type": [ "object", "null" ], "properties": { "filename": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "rowCount": { "type": "integer" }, "sample": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/developer/catalog-imports/{id}/advance": { "post": { "summary": "Advance the next bounded discovery step", "description": "Advances one browser-driven discovery step; polling the job alone does not drive all future discovery.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated visible job. The client drives subsequent steps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "storeUrl": { "type": "string" }, "mode": { "type": "string" }, "targetId": { "type": [ "integer", "null" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "existingProductId": { "type": [ "integer", "null" ] }, "existingPublished": { "type": "boolean" }, "matchConflict": { "type": "boolean" } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "progress": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pendingPages": { "type": "integer" }, "minimumPaidPriceCents": { "type": "integer", "minimum": 0 }, "export": { "type": [ "object", "null" ], "properties": { "filename": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "rowCount": { "type": "integer" }, "sample": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/developer/catalog-imports/{id}/commit": { "post": { "summary": "Save reviewed products as drafts", "description": "Copy selected media before committing. Published products are skipped; matching existing drafts requires explicit allowUpdates. A completed-job replay returns the existing result rather than republishing.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Completed visible job with saved-product results; repeated completed commits return the job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "storeUrl": { "type": "string" }, "mode": { "type": "string" }, "targetId": { "type": [ "integer", "null" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "existingProductId": { "type": [ "integer", "null" ] }, "existingPublished": { "type": "boolean" }, "matchConflict": { "type": "boolean" } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "progress": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pendingPages": { "type": "integer" }, "minimumPaidPriceCents": { "type": "integer", "minimum": 0 }, "export": { "type": [ "object", "null" ], "properties": { "filename": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "rowCount": { "type": "integer" }, "sample": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "confirmed: true (required)", "products: array (required)", "allowUpdates: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmed": { "const": true }, "products": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "existingProductId": { "type": [ "integer", "null" ] }, "existingPublished": { "type": "boolean" }, "matchConflict": { "type": "boolean" } }, "additionalProperties": true } }, "allowUpdates": { "type": "boolean" } }, "required": [ "confirmed", "products" ], "additionalProperties": true } } } } } }, "/api/developer/catalog-imports/{id}/delivery-manifest": { "post": { "summary": "Match an export to completed import results", "description": "linkColumns is a JSON-encoded array of export header names. Review exact, ambiguous and unmatched product matches before starting file imports.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Manifest with rows, direct links, productId, and exact/ambiguous/unmatched state; review every match.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string" } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "export: string (required)", "nameColumn: string", "linkColumns: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "export": { "type": "string", "format": "binary" }, "nameColumn": { "type": "string" }, "linkColumns": { "type": "string" } }, "required": [ "export" ], "additionalProperties": true } } } } } }, "/api/developer/catalog-imports/{id}/delivery/{productId}": { "get": { "summary": "List delivery upload jobs for an imported product", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upload job list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] }, "post": { "summary": "Start a remote-file copy", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "202 with upload job; repeated source requests use the job/product/source identity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "url: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ], "additionalProperties": true } } } } } }, "/api/developer/catalog-imports/{id}/delivery/{productId}/{uploadId}": { "get": { "summary": "Inspect an upload", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current authorized job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/developer/catalog-imports/{id}/delivery/{productId}/{uploadId}/retry": { "post": { "summary": "Retry eligible failed delivery work", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current job; a remote import can restart from the source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/developer/catalog-imports/{id}/delivery/{productId}/direct": { "post": { "summary": "Start or resume multipart delivery upload", "description": "Catalog delivery forces multipart mode. The product must be part of this completed import and within the actor product scope.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "201 with job and upload-session instructions; catalog delivery forces multipart mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "filename: string (required)", "sizeBytes: integer (required)", "mimeType: string", "multipart: boolean", "fileFingerprint: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 10000000000 }, "mimeType": { "type": "string" }, "multipart": { "type": "boolean" }, "fileFingerprint": { "type": "string", "pattern": "^v1:[a-f0-9]{64}$" } }, "required": [ "filename", "sizeBytes" ], "additionalProperties": true } } } } } }, "/api/developer/catalog-imports/{id}/delivery/{productId}/direct/{uploadId}/cancel": { "post": { "summary": "Cancel a multipart upload", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated job state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/developer/catalog-imports/{id}/delivery/{productId}/direct/{uploadId}/complete": { "post": { "summary": "Verify multipart completion and attachment", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current job and attachment outcome; do not attach an incomplete file yourself.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/developer/catalog-imports/{id}/delivery/{productId}/direct/{uploadId}/part": { "post": { "summary": "Prepare an allowed upload part", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed upload instructions; use the returned method, URL, and headers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "partNumber: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 } }, "required": [ "partNumber" ], "additionalProperties": true } } } } } }, "/api/developer/catalog-imports/{id}/delivery/{productId}/local": { "post": { "summary": "Upload a supported buffered local file", "description": "Buffered uploads have a lower limit than direct multipart delivery. The current upload policy determines the returned limit.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "201 with the local upload job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/developer/catalog-imports/{id}/mapping": { "post": { "summary": "Review export column mappings", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated visible job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "storeUrl": { "type": "string" }, "mode": { "type": "string" }, "targetId": { "type": [ "integer", "null" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "existingProductId": { "type": [ "integer", "null" ] }, "existingPublished": { "type": "boolean" }, "matchConflict": { "type": "boolean" } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "progress": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pendingPages": { "type": "integer" }, "minimumPaidPriceCents": { "type": "integer", "minimum": 0 }, "export": { "type": [ "object", "null" ], "properties": { "filename": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "rowCount": { "type": "integer" }, "sample": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "mapping: object (required). Canonical product field to an existing export header." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mapping": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Canonical product field to an existing export header." } }, "required": [ "mapping" ], "additionalProperties": true } } } } } }, "/api/developer/catalog-imports/{id}/media": { "post": { "summary": "Copy a discovered image or audio asset", "description": "The URL must be an allowed candidate source. Only review-stage media is copied.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ asset: ... }; allowed during review, before committing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "kind: images | audio (required)", "url: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "images", "audio" ] }, "url": { "type": "string" } }, "required": [ "kind", "url" ], "additionalProperties": true } } } } } }, "/api/developer/catalog-imports/{id}/retry-discovery": { "post": { "summary": "Retry supported discovery work", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/catalog-imports" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated job; inspect warnings and status before continuing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "storeUrl": { "type": "string" }, "mode": { "type": "string" }, "targetId": { "type": [ "integer", "null" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "audio": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "existingProductId": { "type": [ "integer", "null" ] }, "existingPublished": { "type": "boolean" }, "matchConflict": { "type": "boolean" } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "progress": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pendingPages": { "type": "integer" }, "minimumPaidPriceCents": { "type": "integer", "minimum": 0 }, "export": { "type": [ "object", "null" ], "properties": { "filename": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "rowCount": { "type": "integer" }, "sample": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/catalogImportRoutes.js", "services/catalogImportService.js", "services/catalogImportExtract.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/developer/customers": { "get": { "summary": "Search developer-scoped customers", "description": "Account permissions and assigned products determine scope; query filters cannot expand it. Purchase identifiers can include external/manual references; they are not all eligible managed-payment refund IDs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: rows, total, page, pageSize.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "email_verification_status": { "type": "string" } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query dateRange: string", "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/customers/{customerId}": { "delete": { "summary": "Remove supported developer customer information", "description": "Requires customers.manage, all-products workspace scope and confirm:true or confirmation:\"yes\". This removes the developer contact relationship and supported marketing records, not the global account, purchases or required financial records. Review the account-closure and privacy-request guides.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: ok, alreadyRemoved, already_removed, customer_id, developer_customer_id, message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "alreadyRemoved": { "type": "boolean" }, "already_removed": { "type": "boolean" }, "customer_id": { "type": "integer", "minimum": 1 }, "developer_customer_id": { "type": [ "integer", "string", "null" ] }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The developer customer relationship and all-products workspace scope. Mutations require the operation-specific manage permission; a linked login credential is never changed by a contact edit.", "x-request-fields": [ "confirm: boolean", "confirmation: string", "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js", "services/customerInformationUpdateService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "boolean" }, "confirmation": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": true, "anyOf": [ { "properties": { "confirm": { "const": true } }, "required": [ "confirm" ] }, { "properties": { "confirmation": { "type": "string", "pattern": "^\\s*[Yy][Ee][Ss]\\s*$" } }, "required": [ "confirmation" ] } ] } } } } }, "patch": { "summary": "Edit supported customer fields", "description": "Requires customers.manage and all-products scope, plus confirm:true or confirmation:\"yes\". Names can be cleared independently; first_name/last_name aliases remain accepted. A linked login email cannot be changed here; the customer uses verified account settings. Password replacement is rejected, including legacy generatedPassword/generated_password input. An exclusive unlinked contact email correction clears verification. Supported name/phone corrections can affect the shared profile. Issued invoices and sent messages are not rewritten.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: ok, message, passwordChanged, password_changed, customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" }, "passwordChanged": { "type": "boolean" }, "password_changed": { "type": "boolean" }, "customer": { "type": "object", "properties": { "customer_id": { "type": "integer", "minimum": 1 }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email" }, "phone": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "firstName: string,null", "lastName: string,null", "email: string", "phone: string,null", "reason: string", "confirm: boolean", "confirmation: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "CUSTOMER_EMAIL_VERIFICATION_REQUIRED", "CUSTOMER_ACCOUNT_RECOVERY_REQUIRED", "CUSTOMER_IDENTITY_REVIEW_REQUIRED" ], "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js", "services/customerInformationUpdateService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email" }, "phone": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "confirm": { "type": "boolean" }, "confirmation": { "type": "string" } }, "additionalProperties": true, "anyOf": [ { "properties": { "confirm": { "const": true } }, "required": [ "confirm" ] }, { "properties": { "confirmation": { "type": "string", "pattern": "^\\s*[Yy][Ee][Ss]\\s*$" } }, "required": [ "confirmation" ] } ] } } } } } }, "/api/developer/customers/{customerId}/activity": { "get": { "summary": "Read customer activity", "description": "Activity uses camelCase fields; connection and note rows use database-style names. Plugin connections additionally filter fields: customers.view permits customer identity, device_hash and engagement_signal_id; serials.view permits serial_id/serial_code. Opaque failure_reason and metadata require both, otherwise null/{}. Client parameters cannot grant access. Keep permitted diagnostics private. Internal notes are not customer-visible messages. Notes return the latest 100 rows.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "developerId": { "type": "integer", "minimum": 1 }, "actorType": { "type": [ "string", "null" ] }, "actorUserId": { "type": [ "integer", "null" ] }, "customerId": { "type": [ "integer", "null" ] }, "customerEmail": { "type": [ "string", "null" ] }, "customerName": { "type": [ "string", "null" ] }, "productId": { "type": [ "integer", "null" ] }, "productName": { "type": [ "string", "null" ] }, "serialId": { "type": [ "integer", "null" ] }, "serialCode": { "type": [ "string", "null" ] }, "entitlementId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "orderId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "eventType": { "type": "string" }, "severity": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.view and all-products workspace scope; queries stay developer-scoped.", "x-request-fields": [ "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js", "services/platformEventService.js" ] } }, "/api/developer/customers/{customerId}/notes": { "get": { "summary": "Read internal support notes", "description": "Activity uses camelCase fields; connection and note rows use database-style names. Plugin connections additionally filter fields: customers.view permits customer identity, device_hash and engagement_signal_id; serials.view permits serial_id/serial_code. Opaque failure_reason and metadata require both, otherwise null/{}. Client parameters cannot grant access. Keep permitted diagnostics private. Internal notes are not customer-visible messages. Notes return the latest 100 rows.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: notes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "developer_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "author_user_id": { "type": [ "integer", "null" ] }, "note": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.view and all-products workspace scope; queries stay developer-scoped.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ] }, "post": { "summary": "Add an internal customer support note", "description": "Does not send the note to the customer. Avoid credentials, full serials and unnecessary sensitive information.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: note.", "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "developer_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "author_user_id": { "type": [ "integer", "null" ] }, "note": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.manage and all-products workspace scope.", "x-request-fields": [ "note: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string" } }, "required": [ "note" ], "additionalProperties": true } } } } } }, "/api/developer/customers/{customerId}/plugin-connections": { "get": { "summary": "Read customer plugin-connection activity", "description": "Activity uses camelCase fields; connection and note rows use database-style names. Plugin connections additionally filter fields: customers.view permits customer identity, device_hash and engagement_signal_id; serials.view permits serial_id/serial_code. Opaque failure_reason and metadata require both, otherwise null/{}. Client parameters cannot grant access. Keep permitted diagnostics private. Internal notes are not customer-visible messages. Notes return the latest 100 rows.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "developer_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": [ "integer", "null" ] }, "product_id": { "type": "integer", "minimum": 1 }, "serial_id": { "type": [ "integer", "null" ] }, "developer_customer_id": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "key_id": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "engagement_signal_id": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "event_kind": { "type": "string" }, "status": { "type": "string" }, "plugin_version": { "type": [ "string", "null" ] }, "environment": { "type": [ "string", "null" ] }, "device_hash": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "customer_email": { "type": [ "string", "null" ] }, "serial_code": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.view and all-products workspace scope; queries stay developer-scoped.", "x-request-fields": [ "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ] } }, "/api/developer/customers/{customerId}/resend-activation-email": { "post": { "summary": "Send the supported customer access email", "description": "Uses the stored customer identity, not an arbitrary destination email. This is a transactional access message, not marketing enrollment or proof of inbox delivery.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: email, libraryUrl.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "object", "properties": { "sent": { "type": "boolean" }, "skipped": { "type": "boolean" }, "reason": { "type": "string" }, "error": { "type": "string" }, "providerMessageId": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "libraryUrl": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.manage and all-products workspace scope.", "x-request-fields": [ "productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } } } }, "/api/developer/customers/{customerId}/resend-library-email": { "post": { "summary": "Send the supported customer access email", "description": "Uses the stored customer identity, not an arbitrary destination email. This is a transactional access message, not marketing enrollment or proof of inbox delivery.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: email, libraryUrl.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "object", "properties": { "sent": { "type": "boolean" }, "skipped": { "type": "boolean" }, "reason": { "type": "string" }, "error": { "type": "string" }, "providerMessageId": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "libraryUrl": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.manage and all-products workspace scope.", "x-request-fields": [ "productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } } } }, "/api/developer/customers/{customerId}/resend-verification": { "post": { "summary": "Resend the supported verification message", "description": "Requires customers.manage, all-products scope and a linked account. Already-verified accounts return without another send; delivery failures can return 424.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: success, sent, sentTo, providerMessageId, message, customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "sent": { "type": "boolean" }, "sentTo": { "type": "string", "format": "email" }, "providerMessageId": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email_verification_status": { "type": "string" }, "account_email": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "424": { "description": "A required upstream delivery operation failed; inspect the operation result before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js", "services/customerInformationUpdateService.js" ] } }, "/api/developer/customers/{customerId}/reset-activations": { "post": { "summary": "Reset eligible customer device activations", "description": "Read the returned reset counts. A reset is not a refund, a new product grant or permission for recurring billing.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: reset, serialCount, resetCount.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reset": { "type": "boolean" }, "serialCount": { "type": "integer" }, "resetCount": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "entitlements.manage and all-products workspace scope.", "x-request-fields": [ "productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } } } }, "/api/developer/customers/demo-csv": { "get": { "summary": "Download the customers import template", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/customers/export": { "get": { "summary": "Export authorized customers as CSV", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query dateRange: string", "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/customers/import": { "post": { "summary": "Import reviewed customers rows", "description": "Send a CSV file under file or the named JSON row array. Inspect row errors on 207; do not blindly replay already imported rows. Product mappings do not bypass ownership. Customer imports require customers.manage and all-products scope; purchase imports require entitlements.manage and serial imports require serials.manage, with assigned-product checks. Purchase import does not collect payment or transfer provider billing authority and disables purchase marketing/email activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: success, importedCount, insertedCount, errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "importedCount": { "type": "integer" }, "insertedCount": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "207": { "description": "Successful idempotent replay or duplicate confirmation; inspect the linked operation contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "importedCount": { "type": "integer" }, "insertedCount": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "file: string", "customers: array", "productMappings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "customers": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "serialCode": { "type": "string" }, "price": { "type": "number" }, "salePrice": { "type": "number" }, "date": { "type": "string" } }, "additionalProperties": true } }, "productMappings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "customers": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "serialCode": { "type": "string" }, "price": { "type": "number" }, "salePrice": { "type": "number" }, "date": { "type": "string" } }, "additionalProperties": true } }, "productMappings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/email-domains": { "get": { "summary": "List sending domains and current sender readiness", "description": "Reads bounded, cached provider status without creating domains, starting verification or writing provider results to the application database; surrounding settings reads can initialize default sender profiles. This is not a zero-write probe. providerReadErrors distinguishes lookup errors from a DNS mismatch. Inspect transactional, marketing and tracking readiness separately; a website SSL certificate does not verify email DNS.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domains, settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "settings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view and all-products workspace scope; effective developer ownership.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerEmailDomainRoutes.js", "services/developerEmailDomainService.js", "services/emailDomainProviderReadService.js", "services/brandDomainReadiness.js" ] }, "post": { "summary": "Register or reuse a developer sending domain", "description": "emailDomain/sendingDomain alias domain; from_local_part aliases fromLocalPart. Local-part input is only the prefix, not an email address. Activating a different domain disables older active sending-domain rows for this developer. Provider creation and DNS checks have side effects; inspect error flags even on 201. Reusing a domain does not guarantee verified DNS or authorize marketing.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: domain, settings, reusedResendDomain, resendError, elasticError.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "settings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "reusedResendDomain": { "type": "boolean" }, "resendError": { "type": "boolean" }, "elasticError": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view plus domains.manage and all-products workspace scope; effective developer ownership.", "x-request-fields": [ "domain: string", "emailDomain: string", "sendingDomain: string", "fromLocalPart: string", "from_local_part: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "INVALID_EMAIL_DOMAIN", "RESERVED_EMAIL_DOMAIN", "RESEND_NOT_CONFIGURED", "RESEND_DOMAIN_CREATE_FAILED" ], "x-source-files": [ "routes/developerEmailDomainRoutes.js", "services/developerEmailDomainService.js", "services/emailDomainProviderReadService.js", "services/brandDomainReadiness.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "emailDomain": { "type": "string" }, "sendingDomain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "from_local_part": { "type": "string" } }, "additionalProperties": true, "anyOf": [ { "required": [ "domain" ] }, { "required": [ "emailDomain" ] }, { "required": [ "sendingDomain" ] } ] } } } } } }, "/api/developer/email-domains/{domainId}/refresh": { "post": { "summary": "Refresh provider verification for an owned sending domain", "description": "Triggers provider verification and persists the observed results. A disabled domain cannot be refreshed. Can recreate a missing provider domain; inspect resendError, elasticError and settings rather than assuming HTTP success means ready. No DNS propagation time is promised.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: domain, settings, reusedResendDomain, resendError, elasticError.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "settings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "reusedResendDomain": { "type": "boolean" }, "resendError": { "type": "boolean" }, "elasticError": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view plus domains.manage and all-products workspace scope; effective developer ownership.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "INVALID_EMAIL_DOMAIN_ID", "EMAIL_DOMAIN_NOT_FOUND", "EMAIL_DOMAIN_DISABLED", "RESEND_NOT_CONFIGURED" ], "x-source-files": [ "routes/developerEmailDomainRoutes.js", "services/developerEmailDomainService.js", "services/emailDomainProviderReadService.js", "services/brandDomainReadiness.js" ] } }, "/api/developer/email-domains/sender-profiles": { "patch": { "summary": "Update selected purpose-specific sender prefixes", "description": "At least one supported purpose must be provided. The same purpose fields are also accepted at the body root. PUT and PATCH share this sparse-update handler; omitted purposes remain unchanged. An active custom domain is required. Saving a sender profile does not verify DNS or send a message.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view plus domains.manage and all-products workspace scope; effective developer ownership.", "x-request-fields": [ "senderProfiles: object", "licensing: value", "notifications: value", "marketing: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "CUSTOM_SENDING_DOMAIN_REQUIRED", "NO_SENDER_PROFILE_UPDATES", "INVALID_SENDER_LOCAL_PART" ], "x-source-files": [ "routes/developerEmailDomainRoutes.js", "services/developerEmailDomainService.js", "services/emailDomainProviderReadService.js", "services/brandDomainReadiness.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "senderProfiles": { "type": "object", "properties": { "licensing": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] }, "notifications": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] }, "marketing": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] } }, "additionalProperties": true }, "licensing": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] }, "notifications": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] }, "marketing": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] } }, "additionalProperties": true, "anyOf": [ { "required": [ "senderProfiles" ] }, { "required": [ "licensing" ] }, { "required": [ "notifications" ] }, { "required": [ "marketing" ] } ] } } } } }, "put": { "summary": "Update selected purpose-specific sender prefixes", "description": "At least one supported purpose must be provided. The same purpose fields are also accepted at the body root. PUT and PATCH share this sparse-update handler; omitted purposes remain unchanged. An active custom domain is required. Saving a sender profile does not verify DNS or send a message.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view plus domains.manage and all-products workspace scope; effective developer ownership.", "x-request-fields": [ "senderProfiles: object", "licensing: value", "notifications: value", "marketing: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "CUSTOM_SENDING_DOMAIN_REQUIRED", "NO_SENDER_PROFILE_UPDATES", "INVALID_SENDER_LOCAL_PART" ], "x-source-files": [ "routes/developerEmailDomainRoutes.js", "services/developerEmailDomainService.js", "services/emailDomainProviderReadService.js", "services/brandDomainReadiness.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "senderProfiles": { "type": "object", "properties": { "licensing": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] }, "notifications": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] }, "marketing": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] } }, "additionalProperties": true }, "licensing": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] }, "notifications": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] }, "marketing": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "localPart": { "type": "string" } }, "required": [ "localPart" ], "additionalProperties": true }, { "type": "object", "properties": { "local_part": { "type": "string" } }, "required": [ "local_part" ], "additionalProperties": true } ] } }, "additionalProperties": true, "anyOf": [ { "required": [ "senderProfiles" ] }, { "required": [ "licensing" ] }, { "required": [ "notifications" ] }, { "required": [ "marketing" ] } ] } } } } } }, "/api/developer/email-domains/settings": { "get": { "summary": "Read active sending identity and blocking reasons", "description": "Can initialize default sender profiles. Use transactionalBlockingReasons or marketingBlockingReasons for the intended purpose, not the legacy combined blockingReasons alone. With marketingTrackingUsable:false, trackClicks/trackOpens are false. Marketing may be usable without tracking only when the configured provider supports disabling unsafe tracking; otherwise it remains blocked. No public call in this guide changes that provider capability. Full wizard readiness is stricter than a single sending purpose. HTTP 200 does not mean sending is enabled.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view and all-products workspace scope; effective developer ownership.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerEmailDomainRoutes.js", "services/developerEmailDomainService.js", "services/emailDomainProviderReadService.js", "services/brandDomainReadiness.js" ] } }, "/api/developer/email-marketing/campaigns": { "get": { "summary": "List campaigns.", "description": "marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "sourceType", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "campaigns[].", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view and assigned-product campaign/audience access.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query status: string", "query sourceType: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] }, "post": { "summary": "Create campaign draft.", "description": "marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Creates campaign draft.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "201": { "description": "201 campaign.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "audience": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "name: string (required)", "subject: string", "preheader: string", "bodyHtml: string", "bodyText: string", "audienceFilter: object", "fromName: string", "fromEmail: string", "replyToEmail: string", "primaryProductId: integer", "heroImageUrl: string", "ctaLabel: string", "ctaUrl: string", "sourceType: string", "sourceId: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "required": [ "name" ] } } } } } }, "/api/developer/email-marketing/campaigns/{campaignId}": { "patch": { "summary": "Update campaign.", "description": "Only draft or scheduled content is editable; sent content is not rewritten. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend. Side effects: Updates campaign draft/scheduled campaign when allowed.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "updated campaign.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "audience": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "name: string", "subject: string", "preheader: string", "bodyHtml: string", "bodyText: string", "audienceFilter: object", "fromName: string", "fromEmail: string", "replyToEmail: string", "primaryProductId: integer", "heroImageUrl: string", "ctaLabel: string", "ctaUrl: string", "sourceType: string", "sourceId: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "CAMPAIGN_NOT_EDITABLE" ], "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/email-marketing/campaigns/{campaignId}/schedule": { "post": { "summary": "Schedule campaign.", "description": "Use a future date and valid IANA timezone. scheduled_at and timezone aliases are accepted. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend. Side effects: Schedules campaign.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "schedule result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "scheduledAt: string (required)", "deliveryTimezone: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "MARKETING_PROVIDER_DISABLED", "MARKETING_PROVIDER_LOCKED", "DEVELOPER_MARKETING_DISABLED", "MARKETING_FROM_EMAIL_REQUIRED", "MARKETING_BUSINESS_ADDRESS_REQUIRED", "MARKETING_BRANDING_REQUIRED", "MARKETING_REPLY_TO_REQUIRED", "MARKETING_SUBJECT_REQUIRED", "MARKETING_CONTENT_REQUIRED", "CAMPAIGN_SEND_STATE_INVALID", "CAMPAIGN_NOT_SCHEDULABLE", "INVALID_SCHEDULED_AT", "INVALID_DELIVERY_TIMEZONE" ], "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledAt": { "type": "string" }, "deliveryTimezone": { "type": "string" } }, "required": [ "scheduledAt" ], "additionalProperties": true } } } } } }, "/api/developer/email-marketing/campaigns/{campaignId}/send-now": { "post": { "summary": "Send campaign now.", "description": "The route can queue asynchronous work or report a processing batch. HTTP success is not inbox delivery; inspect recipients and reports. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend. Side effects: Queues/sends campaign.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "send result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "queued": { "type": "integer" }, "processed": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "deferred": { "type": "integer" }, "skipped": { "type": "integer" }, "remainingQueued": { "type": "integer" }, "pausedUntil": { "type": [ "string", "null" ], "format": "date-time" }, "async": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "MARKETING_PROVIDER_DISABLED", "MARKETING_PROVIDER_LOCKED", "DEVELOPER_MARKETING_DISABLED", "MARKETING_FROM_EMAIL_REQUIRED", "MARKETING_BUSINESS_ADDRESS_REQUIRED", "MARKETING_BRANDING_REQUIRED", "MARKETING_REPLY_TO_REQUIRED", "MARKETING_SUBJECT_REQUIRED", "MARKETING_CONTENT_REQUIRED", "CAMPAIGN_SEND_STATE_INVALID", "CAMPAIGN_SCHEDULED_NOT_DUE", "CAMPAIGN_STATE_CHANGED", "MARKETING_AUDIENCE_EMPTY" ], "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/email-marketing/campaigns/{campaignId}/test": { "post": { "summary": "Send test email.", "description": "Test routing uses the saved developer support recipient. It is not an arbitrary bulk audience send. The saved sender/footer must be ready. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend. Side effects: Sends test email when provider configured.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "test-send result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" }, "provider": { "type": "string" }, "transactionId": { "type": [ "string", "null" ] }, "recipientEmail": { "type": "string", "format": "email" }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "email: string", "to: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "MARKETING_PROVIDER_DISABLED", "MARKETING_PROVIDER_LOCKED", "DEVELOPER_MARKETING_DISABLED", "MARKETING_FROM_EMAIL_REQUIRED", "MARKETING_BUSINESS_ADDRESS_REQUIRED", "MARKETING_BRANDING_REQUIRED", "MARKETING_REPLY_TO_REQUIRED", "MARKETING_SUBJECT_REQUIRED", "MARKETING_CONTENT_REQUIRED", "TEST_RECIPIENT_REQUIRED" ], "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "to": { "type": "string", "format": "email" } }, "additionalProperties": true } } } } } }, "/api/developer/email-marketing/contacts": { "get": { "summary": "List marketing contacts.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "source", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "segmentId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "filter", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "contacts[].", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "customer_id": { "type": "integer", "minimum": 1 }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "consent_status": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "canExclude": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query status: string", "query source: string", "query productId: integer", "query segmentId: integer", "query filter: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/email-marketing/contacts/import": { "post": { "summary": "Import subscribers.", "description": "Send confirmed:true (or confirm:true). Confirm that the contacts belong to your customer/audience list. Import activity uses the current audience policy and cannot override an unsubscribe or suppression. Inspect each row error and skipped count. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Creates/updates subscribers with consent metadata.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "201": { "description": "import result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rowsUploaded": { "type": "integer" }, "validRows": { "type": "integer" }, "imported": { "type": "integer" }, "updated": { "type": "integer" }, "duplicates": { "type": "integer" }, "skippedInvalidEmail": { "type": "integer" }, "skippedMissingEmail": { "type": "integer" }, "skippedUnsubscribed": { "type": "integer" }, "skippedSuppressed": { "type": "integer" }, "productAssociationsAdded": { "type": "integer" }, "skipped": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "email": { "type": "string", "format": "email" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [ "csv: string", "text: string", "importText: string", "rows: array", "contacts: array", "mapping: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "confirmed: boolean", "confirm: boolean", "source: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js", "services/marketingAudienceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string" }, "text": { "type": "string" }, "importText": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true } }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } }, "additionalProperties": true } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "confirmed": { "type": "boolean" }, "confirm": { "type": "boolean" }, "source": { "type": "string" } }, "additionalProperties": true, "anyOf": [ { "properties": { "confirmed": { "const": true } }, "required": [ "confirmed" ] }, { "properties": { "confirm": { "const": true } }, "required": [ "confirm" ] } ] } } } } } }, "/api/developer/email-marketing/contacts/import/preview": { "post": { "summary": "Preview contact import.", "description": "Preview reads the CSV header and mapped rows; use csv/importText/text for header suggestions. It does not import or send. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Changes or processes the authorized resource: Preview contact import.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "preview rows/errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "headers": { "type": "array", "items": { "type": "string" } }, "suggestedMapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "previewRows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "customer_id": { "type": "integer", "minimum": 1 }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "consent_status": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true } }, "report": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [ "csv: string", "text: string", "importText: string", "rows: array", "contacts: array", "mapping: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "confirmed: boolean", "confirm: boolean", "source: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js", "services/marketingAudienceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string" }, "text": { "type": "string" }, "importText": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true } }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } }, "additionalProperties": true } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "confirmed": { "type": "boolean" }, "confirm": { "type": "boolean" }, "source": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/email-marketing/settings": { "get": { "summary": "Fetch marketing settings.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "developerId": { "type": "integer", "minimum": 1 }, "marketingEnabled": { "type": "boolean" }, "fromName": { "type": "string" }, "fromEmail": { "type": "string" }, "replyToEmail": { "type": "string" }, "defaultFooterCompanyName": { "type": "string" }, "defaultFooterAddress": { "type": "string" }, "providerEnabled": { "type": "boolean" }, "testMode": { "type": "boolean" }, "pricePer1000Cents": { "type": "integer", "minimum": 0 }, "includedMonthlyEmails": { "type": "integer" }, "clickTrackingEnabled": { "type": "boolean" }, "emailSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] }, "patch": { "summary": "Update marketing settings.", "description": "From address must be verified. This account setting does not bypass provider configuration, sender readiness or suppression. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Writes marketing settings.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "updated settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "developerId": { "type": "integer", "minimum": 1 }, "marketingEnabled": { "type": "boolean" }, "fromName": { "type": "string" }, "fromEmail": { "type": "string" }, "replyToEmail": { "type": "string" }, "defaultFooterCompanyName": { "type": "string" }, "defaultFooterAddress": { "type": "string" }, "providerEnabled": { "type": "boolean" }, "testMode": { "type": "boolean" }, "pricePer1000Cents": { "type": "integer", "minimum": 0 }, "includedMonthlyEmails": { "type": "integer" }, "clickTrackingEnabled": { "type": "boolean" }, "emailSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [ "marketingEnabled: boolean", "fromName: string", "fromEmail: string", "replyToEmail: string", "defaultFooterCompanyName: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "marketingEnabled": { "type": "boolean" }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "defaultFooterCompanyName": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/email-marketing/suppressions": { "get": { "summary": "List suppressions.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "suppression rows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "suppressions": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "reason": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/email-marketing/usage": { "get": { "summary": "Fetch email marketing usage.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "usage summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "usage": { "type": "array", "items": { "type": "object", "properties": { "usage_month": { "type": "string" }, "emails_sent_count": { "type": "integer" }, "total_cents": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } }, "includedMonthlyEmails": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/google-analytics": { "delete": { "summary": "Disconnect GA4 settings", "description": "Requires settings access and all-products scope; mutations require settings.manage. Tracking readiness also requires the current verified custom domain. Saved settings are not analytics consent.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: measurementId, enabled, domain, domainStatus, trackingReady, canManage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "measurementId": { "type": "string" }, "enabled": { "type": "boolean" }, "domain": { "type": "string" }, "domainStatus": { "type": "string" }, "trackingReady": { "type": "boolean" }, "canManage": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerGoogleAnalyticsRoutes.js", "services/developerGoogleAnalyticsService.js" ] }, "get": { "summary": "Read settings and management capability", "description": "Requires settings access and all-products scope; mutations require settings.manage. Tracking readiness also requires the current verified custom domain. Saved settings are not analytics consent.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: measurementId, enabled, domain, domainStatus, trackingReady, canManage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "measurementId": { "type": "string" }, "enabled": { "type": "boolean" }, "domain": { "type": "string" }, "domainStatus": { "type": "string" }, "trackingReady": { "type": "boolean" }, "canManage": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerGoogleAnalyticsRoutes.js", "services/developerGoogleAnalyticsService.js" ] }, "put": { "summary": "Save supported GA4 settings", "description": "Requires settings access and all-products scope; mutations require settings.manage. Tracking readiness also requires the current verified custom domain. Saved settings are not analytics consent.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: measurementId, enabled, domain, domainStatus, trackingReady, canManage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "measurementId": { "type": "string" }, "enabled": { "type": "boolean" }, "domain": { "type": "string" }, "domainStatus": { "type": "string" }, "trackingReady": { "type": "boolean" }, "canManage": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "measurementId: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerGoogleAnalyticsRoutes.js", "services/developerGoogleAnalyticsService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "measurementId": { "type": "string", "pattern": "^G-[A-Z0-9]+$" } }, "required": [ "measurementId" ], "additionalProperties": true } } } } } }, "/api/developer/manual-grants": { "post": { "summary": "Grant access to an owned product with an audit reason", "description": "email is required even with customerId. Supports documented snake_case aliases. grantType defaults to access (or new_serial for a non-subscription serial-only product); createSerial:true is a compatibility shortcut. An existing active grant can return skipped:true/already_granted with no new purchase. Inspect created, email and entitlement outcomes. This writes customer/access/purchase records and normally attempts customer email; sendEmail:false disables that send. It is not a paid checkout, processor refund or migration of stored card details. Subscription grants require an explicit duration and use their own workflow. Timed manual keep-products grants immediately give permanent ownership of the products included when granted, without payment. Those products remain owned after subscription cancellation or expiry; future paid subscription benefits still require billing setup. Explicit developer access removal can revoke the grant. Lifetime grants provide complimentary ongoing access and do not count as paid ownership. An existing customer email is reused across developer workspaces without reassigning its legacy owner. No whole-workflow transaction or blanket replay guarantee is promised.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions-and-grants" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: success, grantType, customer, accountLink, product, purchase, items, entitlements, serial, serials, email, created, skipped, reason, licenseType.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "grantType": { "type": "string" }, "customer": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "accountLink": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "product": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "purchase": { "type": [ "object", "null" ] }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "entitlements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "serial": { "type": [ "object", "null" ] }, "serials": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "email": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created": { "type": "boolean" }, "skipped": { "type": "boolean" }, "reason": { "type": "string" }, "licenseType": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "entitlements.manage and assigned-product access; product ownership and customer matching remain enforced.", "x-request-fields": [ "productId: integer (required)", "email: string (required)", "customerId: integer", "firstName: string", "lastName: string", "reason: string (required)", "internalNote: string", "licenseType: paid | free | nfr | beta | promo | reseller | manual | migration | subscription", "grantType: access | existing_serial | new_serial", "createSerial: boolean", "serialId: integer", "serialCode: string", "sendEmail: boolean", "grantRequestId: string", "subscriptionGrantDuration: week | month | three_months | custom | lifetime", "subscriptionGrantEndDate: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "PRODUCT_REQUIRED", "REASON_REQUIRED", "CUSTOMER_EMAIL_REQUIRED", "INVALID_GRANT_TYPE", "PRODUCT_SERIALS_DISABLED", "SUBSCRIPTION_GRANT_DURATION_REQUIRED", "CUSTOMER_IDENTITY_CHANGED" ], "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js", "services/developerCustomerSerialService.js", "services/manualSubscriptionGrantService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "customerId": { "type": "integer", "minimum": 1 }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "reason": { "type": "string" }, "internalNote": { "type": "string" }, "licenseType": { "enum": [ "paid", "free", "nfr", "beta", "promo", "reseller", "manual", "migration", "subscription" ] }, "grantType": { "enum": [ "access", "existing_serial", "new_serial" ] }, "createSerial": { "type": "boolean" }, "serialId": { "type": "integer", "minimum": 1 }, "serialCode": { "type": "string" }, "sendEmail": { "type": "boolean" }, "grantRequestId": { "type": "string" }, "subscriptionGrantDuration": { "enum": [ "week", "month", "three_months", "custom", "lifetime" ] }, "subscriptionGrantEndDate": { "type": "string", "format": "date" } }, "required": [ "productId", "email", "reason" ], "additionalProperties": true } } } } } }, "/api/developer/marketing/ai/generate-banner": { "post": { "summary": "Request campaign banner assistance.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Request campaign banner assistance. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "generatedAssetId": { "type": "integer", "minimum": 1 }, "imageUrl": { "type": "string" }, "assetUrl": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "fileSize": { "type": "integer" }, "format": { "type": "string" }, "promptUsed": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "productId: integer", "dealId: integer", "campaignId: integer", "campaignType: string", "tone: string", "audienceType: string", "desiredLength: string", "instructions: string", "prompt: string", "existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "count: integer", "selectedText: string", "fullDraft: string", "instruction: string", "visualDirection: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "dealId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "campaignType": { "type": "string" }, "tone": { "type": "string" }, "audienceType": { "type": "string" }, "desiredLength": { "type": "string" }, "instructions": { "type": "string" }, "prompt": { "type": "string" }, "existingDraft": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "count": { "type": "integer" }, "selectedText": { "type": "string" }, "fullDraft": { "type": "string" }, "instruction": { "type": "string" }, "visualDirection": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/ai/generate-draft": { "post": { "summary": "Prepare an AI-assisted campaign draft.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Prepare an AI-assisted campaign draft. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subjectLines": { "type": "array", "items": { "type": "string" } }, "previewText": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyMarkdown": { "type": "string" }, "ctaText": { "type": "string" }, "ctaUrl": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "provider": { "type": "string" }, "model": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "productId: integer", "dealId: integer", "campaignId: integer", "campaignType: string", "tone: string", "audienceType: string", "desiredLength: string", "instructions: string", "prompt: string", "existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "count: integer", "selectedText: string", "fullDraft: string", "instruction: string", "visualDirection: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "dealId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "campaignType": { "type": "string" }, "tone": { "type": "string" }, "audienceType": { "type": "string" }, "desiredLength": { "type": "string" }, "instructions": { "type": "string" }, "prompt": { "type": "string" }, "existingDraft": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "count": { "type": "integer" }, "selectedText": { "type": "string" }, "fullDraft": { "type": "string" }, "instruction": { "type": "string" }, "visualDirection": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/ai/generate-preview-text": { "post": { "summary": "Generate preview-text suggestions.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Generate preview-text suggestions. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "previewTextOptions": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "provider": { "type": "string" }, "model": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "productId: integer", "dealId: integer", "campaignId: integer", "campaignType: string", "tone: string", "audienceType: string", "desiredLength: string", "instructions: string", "prompt: string", "existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "count: integer", "selectedText: string", "fullDraft: string", "instruction: string", "visualDirection: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "dealId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "campaignType": { "type": "string" }, "tone": { "type": "string" }, "audienceType": { "type": "string" }, "desiredLength": { "type": "string" }, "instructions": { "type": "string" }, "prompt": { "type": "string" }, "existingDraft": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "count": { "type": "integer" }, "selectedText": { "type": "string" }, "fullDraft": { "type": "string" }, "instruction": { "type": "string" }, "visualDirection": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/ai/generate-scheduled-deal-draft": { "post": { "summary": "Prepare an AI-assisted deal campaign draft.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Prepare an AI-assisted deal campaign draft. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subjectLines": { "type": "array", "items": { "type": "string" } }, "previewText": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyMarkdown": { "type": "string" }, "ctaText": { "type": "string" }, "ctaUrl": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "productId: integer", "dealId: integer (required)", "campaignId: integer", "campaignType: string", "tone: string", "audienceType: string", "desiredLength: string", "instructions: string", "prompt: string", "existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "count: integer", "selectedText: string", "fullDraft: string", "instruction: string", "visualDirection: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAiService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "dealId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "campaignType": { "type": "string" }, "tone": { "type": "string" }, "audienceType": { "type": "string" }, "desiredLength": { "type": "string" }, "instructions": { "type": "string" }, "prompt": { "type": "string" }, "existingDraft": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "count": { "type": "integer" }, "selectedText": { "type": "string" }, "fullDraft": { "type": "string" }, "instruction": { "type": "string" }, "visualDirection": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true, "required": [ "dealId" ] } } } } } }, "/api/developer/marketing/ai/generate-subjects": { "post": { "summary": "Generate subject suggestions.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Generate subject suggestions. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subjectLines": { "type": "array", "items": { "type": "string" } }, "previewTextOptions": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "provider": { "type": "string" }, "model": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "productId: integer", "dealId: integer", "campaignId: integer", "campaignType: string", "tone: string", "audienceType: string", "desiredLength: string", "instructions: string", "prompt: string", "existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "count: integer", "selectedText: string", "fullDraft: string", "instruction: string", "visualDirection: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "dealId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "campaignType": { "type": "string" }, "tone": { "type": "string" }, "audienceType": { "type": "string" }, "desiredLength": { "type": "string" }, "instructions": { "type": "string" }, "prompt": { "type": "string" }, "existingDraft": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "count": { "type": "integer" }, "selectedText": { "type": "string" }, "fullDraft": { "type": "string" }, "instruction": { "type": "string" }, "visualDirection": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/ai/rewrite": { "post": { "summary": "Rewrite supplied draft content.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Rewrite supplied draft content. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rewrittenText": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "provider": { "type": "string" }, "model": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "productId: integer", "dealId: integer", "campaignId: integer", "campaignType: string", "tone: string", "audienceType: string", "desiredLength: string", "instructions: string", "prompt: string", "existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "count: integer", "selectedText: string", "fullDraft: string", "instruction: string", "visualDirection: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAiService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "dealId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "campaignType": { "type": "string" }, "tone": { "type": "string" }, "audienceType": { "type": "string" }, "desiredLength": { "type": "string" }, "instructions": { "type": "string" }, "prompt": { "type": "string" }, "existingDraft": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "count": { "type": "integer" }, "selectedText": { "type": "string" }, "fullDraft": { "type": "string" }, "instruction": { "type": "string" }, "visualDirection": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true, "anyOf": [ { "required": [ "selectedText" ] }, { "required": [ "fullDraft" ] } ] } } } } } }, "/api/developer/marketing/audience/estimate": { "post": { "summary": "Estimate eligible recipients before sending.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Side effects: Estimate eligible recipients before sending. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "audienceFilter: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/automation/audit-events": { "get": { "summary": "Read automation activity history.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "workflowId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "auditEvents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "workflow_id": { "type": "integer", "minimum": 1 }, "event_type": { "type": "string" }, "message": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query workflowId: integer", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/automation/process": { "post": { "summary": "Request bounded processing under the supported permission boundary.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Processes real eligible queued work for the workspace. Do not use as a health check. Side effects: Request bounded processing under the supported permission boundary. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "processed": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "deliveryUnknown": { "type": "integer" }, "usageReconciled": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "deferred": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/automation/queue": { "get": { "summary": "Read queued work and outcomes.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "workflowId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "queue": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "workflow_id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "status": { "type": "string" }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_reason": { "type": [ "string", "null" ] } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query status: string", "query workflowId: integer", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/automation/settings": { "get": { "summary": "Read automation enablement and settings.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "automation_enabled": { "type": "boolean" }, "quiet_hours_enabled": { "type": "boolean" }, "quiet_hours_start": { "type": "string" }, "quiet_hours_end": { "type": "string" }, "timezone": { "type": "string" }, "smart_send_window_enabled": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] }, "patch": { "summary": "Update automation readiness/settings.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Update automation readiness/settings. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "automation_enabled": { "type": "boolean" }, "quiet_hours_enabled": { "type": "boolean" }, "quiet_hours_start": { "type": "string" }, "quiet_hours_end": { "type": "string" }, "timezone": { "type": "string" }, "smart_send_window_enabled": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "automationEnabled: boolean", "quietHoursEnabled: boolean", "quietHoursStart: string", "quietHoursEnd: string", "timezone: string", "smartSendWindowEnabled: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "automationEnabled": { "type": "boolean" }, "quietHoursEnabled": { "type": "boolean" }, "quietHoursStart": { "type": "string" }, "quietHoursEnd": { "type": "string" }, "timezone": { "type": "string" }, "smartSendWindowEnabled": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/automation/signals": { "get": { "summary": "Read trigger signal activity.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "signalType", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "signal_type": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "windows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query signalType: string", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/automation/signals/test": { "post": { "summary": "Create a controlled test signal.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. This is not a dry-run endpoint: a signal can queue eligible workflow work. Current permission, consent and suppression rules still apply. Side effects: Create a controlled test signal. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [], "responses": { "201": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "signal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "queued": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "signalType: string (required)", "customerId: integer", "developerCustomerId: integer", "productId: integer", "entitlementId: integer", "serialId: integer", "email: string", "source: string", "sourceId: string", "signalCount: integer", "occurredAt: string,null", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signalType": { "type": "string" }, "customerId": { "type": "integer", "minimum": 1 }, "developerCustomerId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "entitlementId": { "type": "integer", "minimum": 1 }, "serialId": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "source": { "type": "string" }, "sourceId": { "type": "string" }, "signalCount": { "type": "integer" }, "occurredAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "required": [ "signalType" ], "additionalProperties": true } } } } } }, "/api/developer/marketing/automation/suppression-rules": { "get": { "summary": "Read suppression rules.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "workflowId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "workflow_id": { "type": "integer", "minimum": 1 }, "rule_type": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "segment_id": { "type": "integer", "minimum": 1 }, "cooldown_hours": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query workflowId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/automation/workflows": { "get": { "summary": "List automation workflows.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "triggerType", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" }, "segment_id": { "type": "integer", "minimum": 1 }, "campaign_id": { "type": "integer", "minimum": 1 }, "delay_minutes": { "type": "integer" }, "quiet_hours_strategy": { "type": "string" }, "smart_timing_enabled": { "type": "boolean" }, "suppression_policy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "message_template": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query status: string", "query triggerType: string", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] }, "post": { "summary": "Create an automation workflow.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Create an automation workflow. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [], "responses": { "201": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" }, "segment_id": { "type": "integer", "minimum": 1 }, "campaign_id": { "type": "integer", "minimum": 1 }, "delay_minutes": { "type": "integer" }, "quiet_hours_strategy": { "type": "string" }, "smart_timing_enabled": { "type": "boolean" }, "suppression_policy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "message_template": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "name: string (required)", "status: draft | active | paused | archived", "triggerType: string (required)", "segmentId: integer", "campaignId: integer", "delayMinutes: integer", "quietHoursStrategy: defer | skip | ignore", "smartTimingEnabled: boolean", "suppressionPolicy: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "messageTemplate: object", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "required": [ "name", "triggerType" ] } } } } } }, "/api/developer/marketing/automation/workflows/{workflowId}": { "patch": { "summary": "Update the workflow.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Update the workflow. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" }, "segment_id": { "type": "integer", "minimum": 1 }, "campaign_id": { "type": "integer", "minimum": 1 }, "delay_minutes": { "type": "integer" }, "quiet_hours_strategy": { "type": "string" }, "smart_timing_enabled": { "type": "boolean" }, "suppression_policy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "message_template": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "name: string", "status: draft | active | paused | archived", "triggerType: string", "segmentId: integer", "campaignId: integer", "delayMinutes: integer", "quietHoursStrategy: defer | skip | ignore", "smartTimingEnabled: boolean", "suppressionPolicy: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "messageTemplate: object", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/automation/workflows/{workflowId}/suppression-rules": { "post": { "summary": "Create a workflow suppression rule.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Create a workflow suppression rule. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "ruleType: string (required)", "productId: integer", "segmentId: integer", "cooldownHours: integer", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleType": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "segmentId": { "type": "integer", "minimum": 1 }, "cooldownHours": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "required": [ "ruleType" ], "additionalProperties": true } } } } } }, "/api/developer/marketing/campaigns/{campaignId}": { "delete": { "summary": "Delete a campaign when its state allows.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Sending campaigns cannot be deleted. Usage, accounting and suppression records remain; prior unsubscribe links stay valid. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend. Side effects: Delete a campaign when its state allows. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "campaignId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "CAMPAIGN_NOT_DELETABLE" ], "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] }, "get": { "summary": "Read a campaign and its current state.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "audience": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view and assigned-product campaign/audience access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/marketing/campaigns/{campaignId}/cancel": { "post": { "summary": "Cancel supported pending campaign work.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend. Side effects: Cancel supported pending campaign work. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "CAMPAIGN_NOT_CANCELABLE" ], "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/marketing/campaigns/{campaignId}/duplicate": { "post": { "summary": "Duplicate for review with a new schedule.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Duplicate for review with a new schedule. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "audience": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/marketing/campaigns/{campaignId}/name": { "patch": { "summary": "Rename a current or sent campaign", "description": "Rename does not edit a sent message. Requires marketing.manage and all-products scope. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated campaign; this does not rewrite the sent message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [ "name: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": true } } } } } }, "/api/developer/marketing/campaigns/{campaignId}/preview": { "post": { "summary": "Render content without sending to an audience.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Render content without sending to an audience. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/marketing/campaigns/{campaignId}/recipients": { "get": { "summary": "Inspect per-recipient outcomes with query filters.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "status": { "type": "string" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "skip_reason": { "type": [ "string", "null" ] } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view and assigned-product campaign/audience access.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query status: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/marketing/campaigns/{campaignId}/report": { "get": { "summary": "Read campaign delivery, engagement, and attribution context.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. providerStatsStatus separates not_sent, pending, retrying, ready, stale and unavailable. Missing delivered/provider totals are null, not confirmed zeros. stale retains the last usable provider snapshot; unavailable retains recorded events without promising recoverable provider history. Do not resend a campaign to repair reporting. openRate/clickRate are raw ratios; UI availability labels and list-report rate objects must be interpreted separately. marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "number" }, "clickRate": { "type": "number" }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view and assigned-product campaign/audience access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js", "services/marketingCampaignPerformanceSyncService.js" ] } }, "/api/developer/marketing/campaigns/{campaignId}/resume-send": { "post": { "summary": "Resume supported interrupted send processing", "description": "Resume remaining work, not a new campaign or resend of accepted recipients. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend. Side effects: Resume supported interrupted sending after checking recipient outcomes. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: campaign, processed, sent, failed, deferred, skipped, remainingQueued, pausedUntil.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "processed": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "deferred": { "type": "integer" }, "skipped": { "type": "integer" }, "remainingQueued": { "type": "integer" }, "pausedUntil": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "CAMPAIGN_NOT_SENDING" ], "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/marketing/campaigns/{campaignId}/retry-failed": { "post": { "summary": "Retry failed recipients only", "description": "scope defaults to safe. uncertain requires confirmUncertain: true and accepts duplicate-delivery risk. Successful recipients remain excluded. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retry result; successful recipients are not resent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaignId": { "type": "integer", "minimum": 1 }, "scope": { "type": "string" }, "requeued": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [ "scope: safe | uncertain", "confirmUncertain: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "MARKETING_PROVIDER_DISABLED", "MARKETING_PROVIDER_LOCKED", "DEVELOPER_MARKETING_DISABLED", "MARKETING_FROM_EMAIL_REQUIRED", "MARKETING_BUSINESS_ADDRESS_REQUIRED", "MARKETING_BRANDING_REQUIRED", "MARKETING_REPLY_TO_REQUIRED", "MARKETING_SUBJECT_REQUIRED", "MARKETING_CONTENT_REQUIRED", "CAMPAIGN_RETRY_SCOPE_INVALID", "CAMPAIGN_RETRY_CONFIRMATION_REQUIRED", "CAMPAIGN_RETRY_STATE_INVALID" ], "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "safe", "uncertain" ] }, "confirmUncertain": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/campaigns/{campaignId}/retry-summary": { "get": { "summary": "Inspect safe and uncertain failures", "description": "marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current retry summary; inspect it before selecting a scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaignId": { "type": "integer", "minimum": 1 }, "safeCount": { "type": "integer" }, "uncertainCount": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/marketing/campaigns/latest/report": { "get": { "summary": "Read the latest scoped campaign report", "description": "Same availability fields and nullable provider totals as the campaign-specific report. Reports are reads, not provider-history sync or resend commands. marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: recipients, queued, sending, sent, skipped, failed, unsubscribed, bounced, complained, accepted, completed, remaining, opened, clicked, uniqueOpened, uniqueClicked, delivered, recordedDelivered, deliverySource, lastDeliveryAt, recordedOpenEvents, recordedClickEvents, engagementUnchecked, engagementDenominator, providerBounced, providerUnsubscribed, providerComplaints, performanceSource, providerStatsCheckedAt, providerStatsError, providerStatsStatus, attributedOrders, revenueCents, openRate, clickRate, clickToOpenRate, statusBreakdown, progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "number" }, "clickRate": { "type": "number" }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view and assigned-product campaign/audience access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/marketing/contacts/{id}/consent": { "patch": { "summary": "Record a permitted consent change.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. The path ID is the fallback customer ID. Eligible customer activity is required. This does not override a sticky unsubscribe or suppression. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Record a permitted consent change. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "customer_id": { "type": "integer", "minimum": 1 }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "consent_status": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [ "customerId: integer", "email: string", "firstName: string", "lastName: string", "marketingOptIn: boolean", "productId: integer", "orderId: integer", "entitlementId: integer", "serialId: integer", "campaignId: integer", "eventType: string", "consentSource: string", "sourceEventId: string", "occurredAt: string,null", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "marketingOptIn": { "type": "boolean" }, "productId": { "type": "integer", "minimum": 1 }, "orderId": { "type": "integer", "minimum": 1 }, "entitlementId": { "type": "integer", "minimum": 1 }, "serialId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "eventType": { "type": "string" }, "consentSource": { "type": "string" }, "sourceEventId": { "type": "string" }, "occurredAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/contacts/{id}/suppress": { "patch": { "summary": "Update one contact suppression", "description": "Requires marketing.manage and all-products scope. Suppression is not deletion of financial records. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Suppress or resolve the selected contact under the permitted workflow. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: contact, suppressed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "customer_id": { "type": "integer", "minimum": 1 }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "consent_status": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true }, "suppressed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/contacts/bulk-suppress": { "patch": { "summary": "Suppress selected contacts", "description": "Requires marketing.manage and all-products scope. Selected IDs and all-matching cleanup use different checks. All-matching requires a current active-contact filter and expectedTotal; continue using the returned jobId until complete. Changed selection fails rather than silently excluding a new audience. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Suppress a selected audience under all-products permission. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: suppressed, requested, skipped, contacts, jobId, advanced, totalCount, remaining, cumulativeSuppressed, cumulativeSkipped, complete, verificationPending.", "content": { "application/json": { "schema": { "type": "object", "properties": { "suppressed": { "type": "integer" }, "requested": { "type": "integer" }, "skipped": { "type": "integer" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "customer_id": { "type": "integer", "minimum": 1 }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "consent_status": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true } }, "jobId": { "type": "string" }, "advanced": { "type": "integer" }, "totalCount": { "type": "integer" }, "remaining": { "type": "integer" }, "cumulativeSuppressed": { "type": "integer" }, "cumulativeSkipped": { "type": "integer" }, "complete": { "type": "boolean" }, "verificationPending": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [ "ids: array", "contactIds: array", "reason: string", "filter: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "scope: string", "expectedTotal: integer", "jobId: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "contactIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "reason": { "type": "string" }, "filter": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "scope": { "type": "string" }, "expectedTotal": { "type": "integer" }, "jobId": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/contacts/import/demo.csv": { "get": { "summary": "Download the contact-import sample.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "CSV sample.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/marketing/growth-flows": { "get": { "summary": "List flows and their activity.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 }, "required": false, "description": "" }, { "name": "range", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Use all for all-time metrics; otherwise days defaults to 30." } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "queueSnapshotAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query days: integer", "query range: string. Use all for all-time metrics; otherwise days defaults to 30." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] }, "post": { "summary": "Create a flow for a supported template and audience.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Create a flow for a supported template and audience. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [], "responses": { "201": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "name: string", "status: draft | active | paused | archived", "triggerType: string", "segmentId: integer", "campaignId: integer", "delayMinutes: integer", "quietHoursStrategy: defer | skip | ignore", "smartTimingEnabled: boolean", "suppressionPolicy: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "messageTemplate: object", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "type: string (required)", "description: string", "audienceId: integer", "productId: integer", "relatedProductIds: array", "promotionId: integer", "inactiveDays: integer", "setupUrl: string", "releaseUrl: string", "version: string", "downloadUrl: string", "recommendedProductUrl: string", "incentive: object", "sequence: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } }, "additionalProperties": true, "required": [ "type" ] } } } } } }, "/api/developer/marketing/growth-flows/{flowId}": { "get": { "summary": "Read the sequence and step/reward context.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] }, "patch": { "summary": "Update flow configuration.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Update flow configuration. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "name: string", "status: draft | active | paused | archived", "triggerType: string", "segmentId: integer", "campaignId: integer", "delayMinutes: integer", "quietHoursStrategy: defer | skip | ignore", "smartTimingEnabled: boolean", "suppressionPolicy: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "messageTemplate: object", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "type: string", "description: string", "audienceId: integer", "productId: integer", "relatedProductIds: array", "promotionId: integer", "inactiveDays: integer", "setupUrl: string", "releaseUrl: string", "version: string", "downloadUrl: string", "recommendedProductUrl: string", "incentive: object", "sequence: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/growth-flows/{flowId}/activate": { "post": { "summary": "Activate the configured flow.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Activate the configured flow. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/{flowId}/archive": { "post": { "summary": "Archive the selected flow.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Archive the selected flow. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/{flowId}/duplicate": { "post": { "summary": "Copy a flow for review.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Copy a flow for review. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/{flowId}/pause": { "post": { "summary": "Pause future flow work.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Pause future flow work. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/{flowId}/preview": { "get": { "summary": "Preview rendered sequence content.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/{flowId}/recipients": { "get": { "summary": "Review flow recipients", "description": "Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "emailNumber", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: recipients, pagination, search, status, emailNumber.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "workflowId": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "status": { "type": "string" }, "failureReason": { "type": [ "string", "null" ] }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryReviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryReviewOutcome": { "type": [ "string", "null" ] }, "deliveryReviewComplete": { "type": "boolean" }, "deliveryReviewEventsScanned": { "type": "integer" }, "retryUnconfirmedAllowed": { "type": "boolean" }, "productName": { "type": "string" }, "productRole": { "type": "string" } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "additionalProperties": true }, "search": { "type": "string" }, "status": { "type": "string" }, "emailNumber": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query status: string", "query emailNumber: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/{flowId}/recipients/{queueId}/retry": { "post": { "summary": "Retry an eligible failed recipient", "description": "Only a confirmed failed, unsent recipient is eligible. Requires an active flow and no recorded delivery. Sending rechecks consent, suppression and queue rules.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "queueId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated retry outcome after current consent and suppression checks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time" }, "outcome": { "type": "string" }, "eventsScanned": { "type": "integer" }, "retryEligible": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/{flowId}/recipients/{queueId}/retry-unconfirmed": { "post": { "summary": "Recheck and requeue an eligible unconfirmed recipient", "description": "Rechecks provider history before requeueing. Requires delivery_unknown, a complete unconfirmed review at least 125 minutes after the recorded attempt, no provider message/transaction IDs, no sent/opened/clicked event, and an active flow. A duplicate remains possible. Concurrent review/state changes reject the retry.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "queueId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: status, message, checkedAt, outcome, eventsScanned, retryEligible.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time" }, "outcome": { "type": "string" }, "eventsScanned": { "type": "integer" }, "retryEligible": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "acknowledgeDuplicateRisk: true (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "GROWTH_FLOW_DUPLICATE_RISK_ACK_REQUIRED", "GROWTH_FLOW_UNCONFIRMED_RETRY_NOT_ALLOWED", "GROWTH_FLOW_REVIEW_CHANGED", "GROWTH_FLOW_INACTIVE", "GROWTH_FLOW_DELIVERY_RECORDED", "GROWTH_FLOW_RECIPIENT_NOT_FOUND" ], "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledgeDuplicateRisk": { "const": true } }, "required": [ "acknowledgeDuplicateRisk" ], "additionalProperties": true } } } } } }, "/api/developer/marketing/growth-flows/{flowId}/recipients/{queueId}/review": { "post": { "summary": "Check and persist an uncertain delivery outcome", "description": "Persists a provider-history review. A matching acceptance marks sent without resending. Incomplete, ambiguous or unavailable history stays on hold.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "queueId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Review result for the workspace-owned flow recipient.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time" }, "outcome": { "type": "string" }, "eventsScanned": { "type": "integer" }, "retryEligible": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/{flowId}/run": { "post": { "summary": "Run supported flow work; not a consent override", "description": "Launches supported manual audience work. No eligible audience means no permission to send to suppressed contacts. Side effects: Launch supported manual work for the eligible audience. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: flow, signal, launched.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true }, "signal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "launched": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/{flowId}/test-email": { "post": { "summary": "Send a selected test step to the signed-in developer.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. The recipient must be the signed-in developer. Select a valid sequence step; sender/footer readiness still applies. Side effects: Send a selected test step to the signed-in developer. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "emailNumber: integer", "email: string", "to: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailNumber": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "to": { "type": "string", "format": "email" } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/growth-flows/promo-options": { "get": { "summary": "Read eligible promotion/reward choices.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "selectedId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "discountType": { "type": "string" }, "discountValue": { "type": "number" }, "isActive": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query search: string", "query selectedId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/summary": { "get": { "summary": "Read aggregate flow metrics and queue status.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Default 30 days. Archived flows are hidden from flows but retained in totalFlows, archivedFlows, archivedActivity and aggregate history. Queue totals are a current snapshot at queueSnapshotAt, not a date-range delivery count. Revenue is attributed net product revenue after discounts and product refunds/disputes, excluding tax; it is not developer payout earnings. Internal boolean service options are not HTTP query switches. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 3650 }, "required": false, "description": "" }, { "name": "range", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Use all for all time; a day range such as 90d selects that window when days is omitted." } ], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "rangeDays": { "type": [ "integer", "null" ], "description": "Null for range=all; otherwise the effective day count." }, "range": { "type": "string", "enum": [ "all", "days" ] }, "activeFlows": { "type": "integer" }, "archivedFlows": { "type": "integer" }, "archivedActivity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "emailsSent": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true } }, "totalFlows": { "type": "integer" }, "emailsSent": { "type": "integer" }, "revenue": { "type": "number" }, "conversions": { "type": "integer" }, "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "queueSnapshotAt": { "type": [ "string", "null" ], "format": "date-time" }, "recommendations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query days: integer", "query range: string. Use all for all time; a day range such as 90d selects that window when days is omitted." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js", "services/marketingReportingService.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/marketing/growth-flows/templates": { "get": { "summary": "List supported template definitions.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [], "responses": { "200": { "description": "Scoped current records or rendered preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/templates/{type}/activate": { "post": { "summary": "Activate a supported template workflow.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Activate a supported template workflow. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true }, "created": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/growth-flows/templates/{type}/pause": { "post": { "summary": "Pause the corresponding template workflow.", "description": "Automation and most growth-flow routes require marketing.manage and all-products scope. Template listing requires authenticated marketing view access. Requires marketing.manage and all-products scope, except template listing requires marketing view. Provider acceptance is not proof of inbox delivery. Side effects: Pause the corresponding template workflow. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/growth-flows" }, "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation result; provider delivery and accounting must be checked separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "triggerType": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "campaignId": { "type": "integer", "minimum": 1 }, "delayMinutes": { "type": "integer", "minimum": 0 }, "quietHoursStrategy": { "type": "string", "enum": [ "defer", "skip", "ignore" ] }, "smartTimingEnabled": { "type": "boolean" }, "suppressionPolicy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messageTemplate": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" } }, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "type": { "type": "string" }, "description": { "type": "string" }, "audienceId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "relatedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "promotionId": { "type": "integer", "minimum": 1 }, "inactiveDays": { "type": "integer" }, "setupUrl": { "type": "string" }, "releaseUrl": { "type": "string" }, "version": { "type": "string" }, "downloadUrl": { "type": "string" }, "recommendedProductUrl": { "type": "string" }, "incentive": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "promoCodeId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "discountLabel": { "type": "string" } }, "additionalProperties": true }, "sequence": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "delayMinutes": { "type": "integer" }, "emailNumber": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "metrics": { "type": "object", "properties": { "queuedNow": { "type": "integer" }, "sentTotal": { "type": "integer" }, "failedTotal": { "type": "integer" }, "unresolvedTotal": { "type": "integer" }, "emailsSent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "revenue": { "type": "number" } }, "additionalProperties": true }, "stepMetrics": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true }, "created": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingAutomationService.js", "services/emailGrowthFlowService.js" ] } }, "/api/developer/marketing/scheduled-deals/{dealId}/campaign-draft": { "post": { "summary": "Prepare a campaign draft from a deal; does not send it.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Creates a draft, not an approved or sent campaign. AI configuration may fall back to the supported non-AI draft path. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Prepare a campaign draft from a deal; does not send it. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [ { "name": "dealId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "audience": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "imageUrl": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": true }, "warnings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "ai": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and assigned-product campaign/audience access.", "x-request-fields": [ "name: string", "subject: string", "preheader: string", "bodyHtml: string", "bodyText: string", "audienceFilter: object", "fromName: string", "fromEmail: string", "replyToEmail: string", "primaryProductId: integer", "heroImageUrl: string", "ctaLabel: string", "ctaUrl: string", "sourceType: string", "sourceId: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "useAi: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "useAi": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/segments": { "get": { "summary": "List saved audience segments", "description": "Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: segments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "status": { "type": "string" }, "estimate": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] }, "post": { "summary": "Create a segment", "description": "Side effects: Create a scoped saved segment. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: segment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "segment": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "status": { "type": "string" }, "estimate": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "name: string (required)", "description: string", "filter: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true } }, "required": [ "name" ], "additionalProperties": true } } } } } }, "/api/developer/marketing/segments/{segmentId}": { "delete": { "summary": "Delete a segment", "description": "marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. Side effects: Remove a saved segment. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "segmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: segment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "segment": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "status": { "type": "string" }, "estimate": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view + marketing.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] }, "patch": { "summary": "Edit a segment", "description": "Side effects: Update a saved segment. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "segmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: segment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "segment": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "status": { "type": "string" }, "estimate": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [ "name: string", "description: string", "filter: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } } } }, "/api/developer/marketing/summary": { "get": { "summary": "Read marketing home totals and current activity.", "description": "Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/email-marketing" }, "parameters": [], "responses": { "200": { "description": "Operation result or scoped records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "developerId": { "type": "integer", "minimum": 1 }, "marketingEnabled": { "type": "boolean" }, "fromName": { "type": "string" }, "fromEmail": { "type": "string" }, "replyToEmail": { "type": "string" }, "defaultFooterCompanyName": { "type": "string" }, "defaultFooterAddress": { "type": "string" }, "providerEnabled": { "type": "boolean" }, "testMode": { "type": "boolean" }, "pricePer1000Cents": { "type": "integer", "minimum": 0 }, "includedMonthlyEmails": { "type": "integer" }, "clickTrackingEnabled": { "type": "boolean" }, "emailSettings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportEmailPresent": { "type": "boolean" }, "brandDomainOwnershipReady": { "type": "boolean" }, "customDomain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "fromLocalPart": { "type": "string" }, "senderEmail": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "elasticStatus": { "type": "string" }, "elasticVerified": { "type": "boolean" }, "unifiedVerified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "providerVerification": { "type": "object", "properties": { "resend": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true }, "elastic": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "record": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": [ "string", "number" ] }, "priority": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "sendingEnabled": { "type": "boolean" }, "sendingReady": { "type": "boolean" }, "trackingReady": { "type": "boolean" }, "trackingCertificateReady": { "type": "boolean" }, "certificateExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "providerReadErrors": { "type": "object", "properties": { "resend": { "type": "string" }, "elastic": { "type": "string" } }, "additionalProperties": true }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "domainStatus": { "type": [ "string", "null" ] }, "marketingDomainStatus": { "type": [ "string", "null" ] }, "senderProfiles": { "type": "object", "properties": { "licensing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "notifications": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true }, "marketing": { "type": "object", "properties": { "purpose": { "enum": [ "licensing", "notifications", "marketing" ] }, "label": { "type": "string" }, "localPart": { "type": "string" }, "fromEmail": { "type": "string" }, "editable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "customSendingUsable": { "type": "boolean" }, "transactionalSendingUsable": { "type": "boolean" }, "marketingSendingUsable": { "type": "boolean" }, "marketingTrackingUsable": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "trackOpens": { "type": "boolean" }, "canDisableUnsafeMarketingTracking": { "type": "boolean" }, "unifiedDomainVerified": { "type": "boolean" }, "providerReadiness": { "type": "object", "properties": { "configured": { "type": "boolean" }, "transactional": { "type": "boolean" }, "marketing": { "type": "boolean" }, "tracking": { "type": "boolean" }, "ready": { "type": "boolean" } }, "additionalProperties": true }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "transactionalBlockingReasons": { "type": "array", "items": { "type": "string" } }, "marketingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "trackingBlockingReasons": { "type": "array", "items": { "type": "string" } }, "fallbackSender": { "type": "string" } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "optedInContacts": { "type": "integer" }, "activeMarketingContacts": { "type": "integer" }, "suppressedContacts": { "type": "integer" }, "campaignsTotal": { "type": "integer" }, "campaignsSent": { "type": "integer" }, "sentThisMonth": { "type": "integer" }, "includedMonthlyEmails": { "type": "integer" }, "includedRemainingThisMonth": { "type": "integer" }, "billableThisMonth": { "type": "integer" }, "currentMonthCostCents": { "type": "integer", "minimum": 0 }, "audienceTrend": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "contacts": { "type": "integer" } }, "additionalProperties": true } }, "audienceHealth": { "type": "object", "properties": { "totalDeveloperCustomers": { "type": "integer" }, "activeMarketingContacts": { "type": "integer" }, "pendingContacts": { "type": "integer" }, "transactionalOnlyCustomers": { "type": "integer" }, "unscopedTransactionalOnlyContacts": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "syncMayBeNeeded": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketingRoutes.js", "services/marketingCampaignService.js" ] } }, "/api/developer/onboarding-v2": { "get": { "summary": "Read current account onboarding progress", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Returns not_started without creating progress when no saved state exists.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ] } }, "/api/developer/onboarding-v2/business-brand": { "get": { "summary": "Read business, brand and support-email readiness", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ] }, "patch": { "summary": "Save business identity and visual defaults", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Accepts businessProfile/visualIdentity wrappers or supported flat fields and snake-case aliases. Read current values first: accountType, country and currency have normalization defaults. A saved currency preference does not enable non-USD checkout or payouts. This saves brand values; it does not issue an SSL certificate.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "publicName: string", "accountType: individual | company", "country: string", "defaultCurrency: string", "existingWebsite: string", "supportEmail: string", "tagline: string", "shortDescription: string", "logos: object", "colors: object", "businessProfile: object", "visualIdentity: object", "previewReviewed: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "publicName": { "type": "string" }, "accountType": { "type": "string", "enum": [ "individual", "company" ] }, "country": { "type": "string" }, "defaultCurrency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "existingWebsite": { "type": "string" }, "supportEmail": { "type": "string", "format": "email" }, "tagline": { "type": "string" }, "shortDescription": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "primaryColor": { "type": "string" }, "secondaryColor": { "type": "string" }, "accentColor": { "type": "string" } }, "additionalProperties": true }, "businessProfile": { "type": "object", "properties": { "publicName": { "type": "string" }, "accountType": { "type": "string", "enum": [ "individual", "company" ] }, "country": { "type": "string" }, "defaultCurrency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "existingWebsite": { "type": "string" }, "supportEmail": { "type": "string", "format": "email" }, "tagline": { "type": "string" }, "shortDescription": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "primaryColor": { "type": "string" }, "secondaryColor": { "type": "string" }, "accentColor": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "visualIdentity": { "type": "object", "properties": { "tagline": { "type": "string" }, "shortDescription": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "primaryColor": { "type": "string" }, "secondaryColor": { "type": "string" }, "accentColor": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "previewReviewed": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/business-brand/complete": { "post": { "summary": "Validate brand requirements and advance", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "publicName: string", "accountType: individual | company", "country: string", "defaultCurrency: string", "existingWebsite: string", "supportEmail: string", "tagline: string", "shortDescription: string", "logos: object", "colors: object", "businessProfile: object", "visualIdentity: object", "previewReviewed: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "publicName": { "type": "string" }, "accountType": { "type": "string", "enum": [ "individual", "company" ] }, "country": { "type": "string" }, "defaultCurrency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "existingWebsite": { "type": "string" }, "supportEmail": { "type": "string", "format": "email" }, "tagline": { "type": "string" }, "shortDescription": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "primaryColor": { "type": "string" }, "secondaryColor": { "type": "string" }, "accentColor": { "type": "string" } }, "additionalProperties": true }, "businessProfile": { "type": "object", "properties": { "publicName": { "type": "string" }, "accountType": { "type": "string", "enum": [ "individual", "company" ] }, "country": { "type": "string" }, "defaultCurrency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "existingWebsite": { "type": "string" }, "supportEmail": { "type": "string", "format": "email" }, "tagline": { "type": "string" }, "shortDescription": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "primaryColor": { "type": "string" }, "secondaryColor": { "type": "string" }, "accentColor": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "visualIdentity": { "type": "object", "properties": { "tagline": { "type": "string" }, "shortDescription": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "primaryColor": { "type": "string" }, "secondaryColor": { "type": "string" }, "accentColor": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "previewReviewed": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/business-brand/support-email/verification": { "post": { "summary": "Send support-address verification", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Falls back to the saved support email. Can send a real email; inspect deliveryStatus rather than assuming delivery from HTTP 201. The email token expires after 24 hours.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: supportEmailVerification, alreadyVerified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "alreadyVerified": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "email: string", "supportEmail: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "supportEmail": { "type": "string", "format": "email" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/domain-email": { "get": { "summary": "Read domain, SSL and sender readiness", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Checks reflect the current saved setup; an uninitialized domain can be verified during the read. Use the Domain Setup API to configure records rather than treating review flags as DNS proof.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ] }, "patch": { "summary": "Save domain and email review acknowledgments", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "finalReviewAcknowledged: boolean", "testEmailReviewed: boolean", "managedEmailReviewed: boolean", "optionalCustomSetupStarted: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "finalReviewAcknowledged": { "type": "boolean" }, "testEmailReviewed": { "type": "boolean" }, "managedEmailReviewed": { "type": "boolean" }, "optionalCustomSetupStarted": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/domain-email/complete": { "post": { "summary": "Validate domain and communication requirements", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "finalReviewAcknowledged: boolean", "testEmailReviewed: boolean", "managedEmailReviewed: boolean", "optionalCustomSetupStarted: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "finalReviewAcknowledged": { "type": "boolean" }, "testEmailReviewed": { "type": "boolean" }, "managedEmailReviewed": { "type": "boolean" }, "optionalCustomSetupStarted": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/launch-plan": { "patch": { "summary": "Save launch path and selling models", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Supported snake-case launch_path/selling_models aliases are accepted. licensing_only cannot be combined with a sales channel. Changing selling models can require selling/domain review again.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "launchPath: quick | fully_branded | ", "sellingModels: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "launchPath": { "type": [ "string", "null" ], "enum": [ "quick", "fully_branded", null ] }, "sellingModels": { "type": "array", "items": { "type": "string", "enum": [ "hosted_storefront", "existing_website", "marketplace", "licensing_only" ] } } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/launch-plan/complete": { "post": { "summary": "Validate the saved launch plan and advance", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. A path and at least one model must be saved. Completion can save the provided plan first.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "launchPath: quick | fully_branded | ", "sellingModels: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "launchPath": { "type": [ "string", "null" ], "enum": [ "quick", "fully_branded", null ] }, "sellingModels": { "type": "array", "items": { "type": "string", "enum": [ "hosted_storefront", "existing_website", "marketplace", "licensing_only" ] } } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/payouts": { "get": { "summary": "Read payout setup need, destination and requirements", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ] }, "patch": { "summary": "Record a payout setup decision and review", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. connect/defer records an onboarding choice only. It does not start Stripe onboarding, make a transfer or change a financial flag.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "decision: connect | defer | ", "reviewAcknowledged: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "connect", "defer", "" ] }, "reviewAcknowledged": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/payouts/complete": { "post": { "summary": "Validate or defer payout setup and advance", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "decision: connect | defer | ", "reviewAcknowledged: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "connect", "defer", "" ] }, "reviewAcknowledged": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/payouts/status/refresh": { "post": { "summary": "Refresh the saved provider payout-account status", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. No saved connection returns payoutStatusRefreshed:false. A refresh can query the provider and update saved readiness. It is not a payment; owner-only Connect onboarding remains a separate API.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js", "services/payoutSettlementService.js" ] } }, "/api/developer/onboarding-v2/position": { "patch": { "summary": "Save the last visited accessible onboarding step", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Records the last visited accessible step. It cannot skip prerequisites or mark a step completed.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "step: launch_plan | business_brand | selling_experience | domain_email | payouts | ready_for_products", "stepKey: launch_plan | business_brand | selling_experience | domain_email | payouts | ready_for_products", "currentStep: launch_plan | business_brand | selling_experience | domain_email | payouts | ready_for_products", "current_step: launch_plan | business_brand | selling_experience | domain_email | payouts | ready_for_products" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "stepKey": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "current_step": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] } }, "additionalProperties": true, "anyOf": [ { "required": [ "step" ] }, { "required": [ "stepKey" ] }, { "required": [ "currentStep" ] }, { "required": [ "current_step" ] } ] } } } } } }, "/api/developer/onboarding-v2/ready-for-products": { "get": { "summary": "Read the completed business setup summary", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ] } }, "/api/developer/onboarding-v2/ready-for-products/complete": { "post": { "summary": "Complete setup and record the next destination", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "destination: string", "action: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination": { "type": "string" }, "action": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/reset": { "post": { "summary": "Restart onboarding progress without deleting business assets", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Resets the progress row, launch choices and step statuses. It does not delete existing products, branding, domains, payout accounts, customer records or financial history.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/selling-experience": { "get": { "summary": "Read hosted, existing-site and customer-access setup", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ] }, "patch": { "summary": "Save selling-experience review acknowledgments", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "hostedStorefrontReviewed: boolean", "marketplaceAcknowledged: boolean", "licensingOnlyAcknowledged: boolean", "customerAccessReviewed: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostedStorefrontReviewed": { "type": "boolean" }, "marketplaceAcknowledged": { "type": "boolean" }, "licensingOnlyAcknowledged": { "type": "boolean" }, "customerAccessReviewed": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/selling-experience/complete": { "post": { "summary": "Validate selling experience and advance", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "hostedStorefrontReviewed: boolean", "marketplaceAcknowledged: boolean", "licensingOnlyAcknowledged: boolean", "customerAccessReviewed: boolean", "existingWebsiteIntegration: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostedStorefrontReviewed": { "type": "boolean" }, "marketplaceAcknowledged": { "type": "boolean" }, "licensingOnlyAcknowledged": { "type": "boolean" }, "customerAccessReviewed": { "type": "boolean" }, "existingWebsiteIntegration": { "type": "object", "properties": { "websiteUrl": { "type": "string" }, "integrationApproach": { "type": "string", "enum": [ "storefront_package", "standalone_pages" ] }, "selectedSurfaces": { "type": "array", "items": { "type": "string", "enum": [ "catalog", "product_pages", "deals", "reviews", "customer_account_library", "cart_checkout", "homepage", "about", "support_faq" ] } }, "reviewed": { "type": "boolean" } }, "required": [ "websiteUrl", "integrationApproach" ], "additionalProperties": true } }, "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/selling-experience/existing-website": { "patch": { "summary": "Save the existing website integration plan", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. This replaces the normalized integration selection, not a sparse installation-status patch. Re-read dependencies. A reviewed plan does not prove the embed is installed.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "websiteUrl: string (required)", "integrationApproach: storefront_package | standalone_pages (required)", "selectedSurfaces: array", "reviewed: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "websiteUrl": { "type": "string" }, "integrationApproach": { "type": "string", "enum": [ "storefront_package", "standalone_pages" ] }, "selectedSurfaces": { "type": "array", "items": { "type": "string", "enum": [ "catalog", "product_pages", "deals", "reviews", "customer_account_library", "cart_checkout", "homepage", "about", "support_faq" ] } }, "reviewed": { "type": "boolean" } }, "required": [ "websiteUrl", "integrationApproach" ], "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/selling-experience/hosted-storefront/ensure": { "post": { "summary": "Prepare the hosted storefront and page foundation", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Creates missing storefront/pages but does not publish a live website. The route returns refreshed selling-experience state.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ] } }, "/api/developer/onboarding-v2/selling-experience/hosted-storefront/template": { "patch": { "summary": "Choose a supported saved starter template", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Use a template key returned in templateOptions; templateKey/websiteTemplate/website_template are aliases. A storefront must already exist.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: featureEnabled, entryRoute, onboarding, branding, businessProfile, visualIdentity, supportEmailVerification, requirements, sellingExperience, domainEmail, payouts, readyForProducts, payoutStatusRefreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "branding": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "businessProfile": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "visualIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requirements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sellingExperience": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domainEmail": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payouts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readyForProducts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payoutStatusRefreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [ "template: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "string" } }, "required": [ "template" ], "additionalProperties": true } } } } } }, "/api/developer/onboarding-v2/start": { "post": { "summary": "Start or resume saved onboarding", "description": "The saved step prerequisites and feature configuration apply. Read missing/requirements on failure and resume the indicated entryRoute. A saved review is not publication, domain verification, checkout approval or a payout. Step reads can initialize progress or prepare website page foundations; do not use them as zero-side-effect health probes. Ignores body fields; repeated calls reuse saved state.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: featureEnabled, entryRoute, onboarding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureEnabled": { "type": "boolean" }, "entryRoute": { "type": "string" }, "onboarding": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "onboardingVersion": { "type": "string" }, "overallStatus": { "type": "string" }, "currentStep": { "type": "string", "enum": [ "launch_plan", "business_brand", "selling_experience", "domain_email", "payouts", "ready_for_products" ] }, "launchPath": { "type": [ "string", "null" ] }, "sellingModels": { "type": "array", "items": { "type": "string" } }, "stepStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resetAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastVisitedStep": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "string" }, "isCurrent": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in developer account. Progress belongs to that account; this is not a product-credential API or a request-selected developer ID.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ] } }, "/api/developer/onboarding-v2/support-email/verify": { "get": { "summary": "Consume a private support-email verification token", "description": "Consumes verification state. Request format=json or Accept:application/json for JSON; ordinary browser success redirects with 303 to business-brand?supportEmailVerified=1. Do not poll or log the token URL. Invalid/expired links are errors, not account sign-in.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/developer-onboarding" }, "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" }, { "name": "format", "in": "query", "schema": { "const": "json" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: verified, supportEmailVerification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "supportEmailVerification": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "303": { "description": "Browser verification succeeded; follow the developer setup continuation.", "headers": { "Location": { "schema": { "type": "string" }, "description": "/developer/onboarding/business-brand?supportEmailVerified=1" } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired credentials or sign-in challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Private token identifies its developer support address.", "x-request-fields": [ "query token: string (required)", "query format: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerOnboardingV2PublicRoutes.js", "routes/developerOnboardingV2Routes.js", "services/developerOnboardingV2Service.js" ] } }, "/api/developer/partners/{relationshipId}": { "get": { "summary": "Read an owned reseller relationship", "description": "partners.view and all-products workspace scope. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/activity": { "get": { "summary": "Read the relationship activity history", "description": "partners.view and all-products workspace scope. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: activity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "activity": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope.", "x-request-fields": [ "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/api-health": { "get": { "summary": "Read key configuration and recent API request statistics", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Status is a configuration heuristic based on enabled API and active keys; request counts use 30 days. It is not a real-time connection or delivery guarantee.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: api_health.", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_health": { "type": "object", "properties": { "status": { "type": "string" }, "request_count": { "type": "integer" }, "error_count": { "type": "integer" }, "error_rate": { "type": "number" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "active_key_count": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/conversations": { "get": { "summary": "Read relationship conversation threads", "description": "partners.view and all-products workspace scope. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] }, "post": { "summary": "Start a relationship conversation", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply. A subject and non-empty body/message are required. Do not put customer credentials or full serials into messages.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: thread, message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "thread": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "message": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [ "body: string", "message: string", "attachments: array", "internal_note: boolean", "subject: string (required)", "threadType: string", "linkedProductId: integer", "linkedExternalOrderId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "message": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "internal_note": { "type": "boolean" }, "subject": { "type": "string" }, "threadType": { "type": "string" }, "linkedProductId": { "type": "integer", "minimum": 1 }, "linkedExternalOrderId": { "type": "integer", "minimum": 1 } }, "required": [ "subject" ], "additionalProperties": true, "anyOf": [ { "required": [ "body" ] }, { "required": [ "message" ] } ] } } } } } }, "/api/developer/partners/{relationshipId}/customers": { "get": { "summary": "Read relationship customer purchase summaries", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. At most 100 customer summaries. Includes private customer identity; no platform-wide customer-list access is granted. /resellers/{relationshipId}/customers is an alias.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: customers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/financials": { "get": { "summary": "Read reported statement totals and historical statements", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Read-only external-sale reporting, not SoundSync payout execution. /resellers/{relationshipId}/financials is an alias.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: financials, statements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "financials": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "statements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/orders": { "get": { "summary": "Read historical external orders", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Default limit 25. The /resellers/{relationshipId}/orders GET alias is supported; its POST write remains retired.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: orders, has_more, limit, offset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [ "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/overview": { "get": { "summary": "Read a relationship and its related records", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Contains private historical records. URL alias: /resellers/{relationshipId}/overview.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship, products, orders, licenses, api_keys, conversations, statements, activity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "orders": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "licenses": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "api_keys": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "conversations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "statements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "activity": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/pause": { "post": { "summary": "Set the relationship to paused", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/products": { "get": { "summary": "List assigned relationship products", "description": "partners.view and all-products workspace scope. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/products/{assignmentId}": { "delete": { "summary": "Remove the supported product assignment", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply. Does not issue a refund or erase customer payment history.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] }, "patch": { "summary": "Update the saved product assignment", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply. assignmentId is the relationship-product record, not the catalog product ID. Omitted saved fields are retained; reload the assignment before editing commercial terms.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [ "productId: integer", "product_id: integer", "status: string", "resellerSku: string", "reseller_sku: string", "resellerProductName: string", "commercialModel: string", "commissionRateBps: integer", "developerRevenueShareBps: integer", "currency: string", "minimumAdvertisedPriceCents: integer", "licenseCap: integer", "monthlyLicenseCap: integer", "apiEnabled: boolean", "manualIssueEnabled: boolean", "staticExportEnabled: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "resellerSku": { "type": "string" }, "reseller_sku": { "type": "string" }, "resellerProductName": { "type": "string" }, "commercialModel": { "type": "string" }, "commissionRateBps": { "type": "integer" }, "developerRevenueShareBps": { "type": "integer" }, "currency": { "type": "string" }, "minimumAdvertisedPriceCents": { "type": "integer" }, "licenseCap": { "type": "integer" }, "monthlyLicenseCap": { "type": "integer" }, "apiEnabled": { "type": "boolean" }, "manualIssueEnabled": { "type": "boolean" }, "staticExportEnabled": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/partners/{relationshipId}/products/assign": { "post": { "summary": "Assign or approve an owned product for this relationship", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply. Supported snake-case commercial fields are also accepted. Commission/share fields are basis points. This saves an assignment; it does not create a sale, license claim or payout. Review commercial terms before saving.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [ "productId: integer", "product_id: integer", "status: string", "resellerSku: string", "reseller_sku: string", "resellerProductName: string", "commercialModel: string", "commissionRateBps: integer", "developerRevenueShareBps: integer", "currency: string", "minimumAdvertisedPriceCents: integer", "licenseCap: integer", "monthlyLicenseCap: integer", "apiEnabled: boolean", "manualIssueEnabled: boolean", "staticExportEnabled: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "resellerSku": { "type": "string" }, "reseller_sku": { "type": "string" }, "resellerProductName": { "type": "string" }, "commercialModel": { "type": "string" }, "commissionRateBps": { "type": "integer" }, "developerRevenueShareBps": { "type": "integer" }, "currency": { "type": "string" }, "minimumAdvertisedPriceCents": { "type": "integer" }, "licenseCap": { "type": "integer" }, "monthlyLicenseCap": { "type": "integer" }, "apiEnabled": { "type": "boolean" }, "manualIssueEnabled": { "type": "boolean" }, "staticExportEnabled": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "anyOf": [ { "required": [ "productId" ] }, { "required": [ "product_id" ] } ] } } } } } }, "/api/developer/partners/{relationshipId}/resume": { "post": { "summary": "Set the relationship to active", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/serials": { "get": { "summary": "Read relationship serial inventory", "description": "partners.view and all-products workspace scope. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serials": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/serials/{poolId}/export": { "get": { "summary": "Download allocated serials as private CSV", "description": "partners.view and all-products workspace scope. Relationship and product ownership checks still apply. The CSV contains one serial license per line, with no header, quotation marks, extra columns or byte-order mark. This read additionally requires partners.manage because the CSV contains usable serials. Preserve the private attachment; never expose it in public logs or documentation.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "poolId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view + partners.manage and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/serials/allocate": { "post": { "summary": "Allocate product serial inventory", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply. The current generated-pool model requires productId/product_id and a regular price or price_cents estimate, including explicit 0 for a free product. quantity defaults to 1. Only generated_serials is supported; serial imports are rejected by this path. Product serial support and an active relationship are checked. The optional four-character prefix is letters/numbers. Expiry must be future-dated; automatic unused-serial removal requires an expiry. Supported snake-case aliases are accepted. This allocates inventory, not proof of a reported sale or payment. No blanket idempotency guarantee; reconcile an uncertain allocation before retrying.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: pool, allocation, quantity, count, items_created, serials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pool": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "allocation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "quantity": { "type": "integer" }, "count": { "type": "integer" }, "items_created": { "type": "integer" }, "serials": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [ "productId: integer", "product_id: integer", "relationshipProductId: integer", "quantity: integer", "batchLabel: string", "notes: string", "fulfillmentMode: \"generated_serials\"", "prefix: string", "price: number", "price_cents: integer", "sale_price: number", "sale_price_cents: integer", "expiresAt: string,null", "autoRevokeUnusedOnExpiry: boolean", "promoStart: string,null", "promoExpires: string,null" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "relationshipProductId": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1 }, "batchLabel": { "type": "string" }, "notes": { "type": "string" }, "fulfillmentMode": { "const": "generated_serials" }, "prefix": { "type": "string", "pattern": "^[A-Za-z0-9]{4}$" }, "price": { "type": "number" }, "price_cents": { "type": "integer" }, "sale_price": { "type": "number" }, "sale_price_cents": { "type": "integer" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "autoRevokeUnusedOnExpiry": { "type": "boolean" }, "promoStart": { "type": [ "string", "null" ], "format": "date-time" }, "promoExpires": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } } } }, "/api/developer/partners/{relationshipId}/settings": { "get": { "summary": "Read the saved relationship settings", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/{relationshipId}/statements": { "get": { "summary": "Read historical reseller statements", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: statements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/directory/resellers": { "get": { "summary": "Browse the eligible reseller directory", "description": "partners.view and all-products workspace scope. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: resellers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resellers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/hub-records/{kind}": { "get": { "summary": "Read the paginated workspace Partner Hub records", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. kind is orders, licenses, conversations, campaigns or statements. Default limit 25, maximum 100; offset is bounded to 1,000,000. Results can contain customer identity and serials and must remain private.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: kind, total, limit, offset, records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "records": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [ "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/overview": { "get": { "summary": "Read the current-month Partner Hub summary", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Reported reseller amounts and estimates are not funded SoundSync-managed checkout balances.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: overview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "overview": { "type": "object", "properties": { "active_resellers": { "type": "integer" }, "pending_relationships": { "type": "integer" }, "external_reported_sales_cents": { "type": "integer" }, "external_order_count": { "type": "integer" }, "licenses_issued": { "type": "integer" }, "expected_payable_cents": { "type": "integer" }, "external_fulfillment_events": { "type": "integer" }, "api_health_warnings": { "type": "integer" }, "unread_partner_messages": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/pool-estimates": { "get": { "summary": "Read serial-pool estimates grouped by currency", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Estimated reseller proceeds are not a customer payment, funded settlement or completed payout.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: estimates, pool_count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "estimates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "pool_count": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/programs": { "get": { "summary": "List developer agreements and proposals.", "description": "Requires partners.view and all-products scope. Agreement setup/preview flags and live accounting availability are separate signals; use the accounting endpoint for funded earnings. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "200": { "description": "Workspace program records.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "kind": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "terms_version": { "type": "integer" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "rate_bps": { "type": "integer" } }, "additionalProperties": true } }, "aggregate_clicks": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "live_accounting_available": { "type": "boolean" }, "summary": { "type": "object", "properties": { "agreement_count": { "type": "integer" }, "active_count": { "type": "integer" }, "pending_acceptance_count": { "type": "integer" }, "aggregate_clicks": { "type": [ "string", "null" ] }, "referral_counts_available": { "type": "boolean" } }, "additionalProperties": true }, "permissions": { "type": "object", "properties": { "can_manage": { "type": "boolean" } }, "additionalProperties": true }, "migration_required": { "type": "boolean" }, "preview_notice": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer workspace with partner permissions and all-products scope; live consent is owner-only.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js" ] }, "post": { "summary": "Create an affiliate or collaborator proposal and invitation.", "description": "Rates are integer basis points from 0 to 10000. Effective terms cannot be backdated. Products must belong to the workspace and pass eligibility/capacity checks. Side effects: Create an affiliate or collaborator proposal and invitation. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "201": { "description": "201 agreement and invitation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object", "properties": {}, "additionalProperties": true }, "invitation": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer workspace with partner permissions and all-products scope; live consent is owner-only.", "x-request-fields": [ "kind: affiliate | collaborator (required)", "recipient_email: string (required)", "name: string (required)", "rate_bps: integer (required)", "product_rates: array (required)", "attribution_window_days: integer", "include_reseller_sales: boolean", "effective_from: string", "send_email: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "affiliate", "collaborator" ] }, "recipient_email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "rate_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "product_rates": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "rate_bps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "product_id", "rate_bps" ], "additionalProperties": true } }, "attribution_window_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "include_reseller_sales": { "type": "boolean" }, "effective_from": { "type": "string", "format": "date-time" }, "send_email": { "type": "boolean" } }, "additionalProperties": true, "required": [ "kind", "recipient_email", "name", "rate_bps", "product_rates" ] } } } } } }, "/api/developer/partners/programs/{id}": { "patch": { "summary": "Propose revised versioned terms.", "description": "Side effects: Propose revised versioned terms. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revised proposal; accepted prior terms are retained.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer workspace with partner permissions and all-products scope; live consent is owner-only.", "x-request-fields": [ "kind: affiliate | collaborator", "recipient_email: string", "name: string", "rate_bps: integer", "product_rates: array", "attribution_window_days: integer", "include_reseller_sales: boolean", "effective_from: string", "send_email: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "affiliate", "collaborator" ] }, "recipient_email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "rate_bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "product_rates": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "rate_bps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "product_id", "rate_bps" ], "additionalProperties": true } }, "attribution_window_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "include_reseller_sales": { "type": "boolean" }, "effective_from": { "type": "string", "format": "date-time" }, "send_email": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/partners/programs/{id}/invite": { "post": { "summary": "Replace or resend a pending invitation.", "description": "Invitation limits and resend cooldown apply; replacement revokes older pending links. Side effects: Replace or resend a pending invitation. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation and delivery result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object", "properties": {}, "additionalProperties": true }, "invitation": { "type": "object", "properties": { "delivery_status": { "type": "string" } }, "additionalProperties": true }, "invite_url": { "type": "string" }, "delivery_status": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer workspace with partner permissions and all-products scope; live consent is owner-only.", "x-request-fields": [ "send_email: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_email": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/partners/programs/{id}/live-consent": { "post": { "summary": "Developer owner explicitly authorizes the current live terms.", "description": "Owner authorization cannot be inherited from a teammate; both parties must consent. Side effects: Developer owner explicitly authorizes the current live terms. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted party, version, and policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "party": { "enum": [ "developer", "recipient" ] }, "terms_version": { "type": "integer", "minimum": 1 }, "policy_version": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer workspace with partner permissions and all-products scope; live consent is owner-only.", "x-request-fields": [ "accept: true (required)", "terms_version: integer (required)", "policy_version: \"soundsync-managed-live-v1\" (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accept": { "const": true }, "terms_version": { "type": "integer", "minimum": 1 }, "policy_version": { "const": "soundsync-managed-live-v1" } }, "required": [ "accept", "terms_version", "policy_version" ], "additionalProperties": true } } } } } }, "/api/developer/partners/programs/{id}/status": { "post": { "summary": "Pause, resume, or end an accepted agreement.", "description": "An ended agreement cannot be resumed; acceptance is required before activation. Side effects: Pause, resume, or end an accepted agreement. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated agreement status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer workspace with partner permissions and all-products scope; live consent is owner-only.", "x-request-fields": [ "status: active | paused | ended (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "active", "paused", "ended" ] } }, "required": [ "status" ], "additionalProperties": true } } } } } }, "/api/developer/partners/programs/accounting": { "get": { "summary": "Read allocations, reversals, destinations, transfers, and funded versus external balances.", "description": "Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "200": { "description": "Accounting summary including balance_details and unfunded_earnings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rollout_enabled": { "type": "boolean" }, "balances": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "balance_details": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "reversals": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "transfers": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "developer_earnings": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "unfunded_earnings": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "consents": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "destinations": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "payout_schedule": { "type": "object", "properties": { "hold_days": { "type": "integer", "minimum": 0 }, "next_run_date": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer workspace with partner permissions and all-products scope; live consent is owner-only.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ] } }, "/api/developer/partners/programs/preview": { "post": { "summary": "Calculate a nonpayable split preview.", "description": "This calculator is not the captured-sale ledger. Use zero processing_fee_cents for the current managed-checkout policy; historical projections can have a different supplied basis. Illustrative calculation only, not a funded balance, accrual, transfer or change to execution flags. Uses accepted active eligible product agreements; recurring products are rejected by this preview. Side effects: Calculate a nonpayable split preview. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "200": { "description": "mode:preview; payable:false; projected allocation and payout plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "const": "preview" }, "payable": { "const": false }, "live_accrual_enabled": { "const": false }, "automatic_payouts_enabled": { "const": false }, "allocation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "refund": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "payout_plan": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true }, "participants": { "type": "array", "items": { "type": "object", "properties": { "agreement_id": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Effective developer workspace with partner permissions and all-products scope; live consent is owner-only.", "x-request-fields": [ "product_id: integer (required)", "subtotal_cents: integer", "discount_cents: integer", "platform_fee_cents: integer", "processing_fee_cents: integer", "affiliate_agreement_id: integer", "currency: string", "collection_provider: stripe | paypal", "cumulative_refund_product_cents: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramPreviewRoutes.js", "services/partnerProgramPreviewService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "subtotal_cents": { "type": "integer", "minimum": 0 }, "discount_cents": { "type": "integer", "minimum": 0 }, "platform_fee_cents": { "type": "integer", "minimum": 0 }, "processing_fee_cents": { "type": "integer", "minimum": 0 }, "affiliate_agreement_id": { "type": "integer", "minimum": 1 }, "currency": { "type": "string" }, "collection_provider": { "type": "string", "enum": [ "stripe", "paypal" ] }, "cumulative_refund_product_cents": { "type": "integer", "minimum": 0 } }, "required": [ "product_id" ], "additionalProperties": true } } } } } }, "/api/developer/partners/requests": { "post": { "summary": "Request a developer-reseller relationship", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply. Creates a relationship request, not approval or permission to sell every product.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [ "partnerId: integer", "partner_id: integer", "message: string", "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerId": { "type": "integer", "minimum": 1 }, "partner_id": { "type": "integer", "minimum": 1 }, "message": { "type": "string" }, "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true, "anyOf": [ { "required": [ "partnerId" ] }, { "required": [ "partner_id" ] } ] } } } } } }, "/api/developer/partners/resellers": { "get": { "summary": "List developer reseller relationships", "description": "partners.view and all-products workspace scope. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: relationships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/resellers/{relationshipId}/accept": { "post": { "summary": "Accept an eligible reseller request", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply. The current request side and status must allow this decision. Re-read state after a conflict.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/partners/resellers/{relationshipId}/api-keys": { "get": { "summary": "Read key metadata without revealing private key material", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Historical GET access is separate from retired key creation/rotation/revocation writes in this developer router.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: api_keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_keys": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/resellers/{relationshipId}/campaigns": { "get": { "summary": "Read relationship scheduled deals", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: campaigns.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] }, "post": { "summary": "Create a reseller scheduled deal", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. A name is required on both create and edit. This is not a sparse PATCH: omitted status becomes draft and omitted descriptions, dates and notes are cleared. Supported snake-case aliases apply. Optional productId/relationshipProductId must resolve to an approved assignment. A partner deal is not a marketing email, managed-checkout promo code or completed sale.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: campaign.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [ "name: string (required)", "description: string", "status: draft | requested | approved | active | paused | ended | settled | disputed | cancelled", "startAt: string,null", "endAt: string,null", "currency: string", "notes: string", "relationshipProductId: integer", "productId: integer", "approved_sale_price_cents: integer", "commercialModel: string", "wholesale_rate_cents: integer", "commissionRateBps: integer", "developerRevenueShareBps: integer", "licenseCap: integer,null" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "requested", "approved", "active", "paused", "ended", "settled", "disputed", "cancelled" ] }, "startAt": { "type": [ "string", "null" ], "format": "date-time" }, "endAt": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "notes": { "type": "string" }, "relationshipProductId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "approved_sale_price_cents": { "type": "integer" }, "commercialModel": { "type": "string" }, "wholesale_rate_cents": { "type": "integer" }, "commissionRateBps": { "type": "integer" }, "developerRevenueShareBps": { "type": "integer" }, "licenseCap": { "type": [ "integer", "null" ] } }, "required": [ "name" ], "additionalProperties": true } } } } } }, "/api/developer/partners/resellers/{relationshipId}/campaigns/{campaignId}": { "patch": { "summary": "Replace reseller scheduled-deal details", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. A name is required on both create and edit. This is not a sparse PATCH: omitted status becomes draft and omitted descriptions, dates and notes are cleared. Supported snake-case aliases apply. Optional productId/relationshipProductId must resolve to an approved assignment. A partner deal is not a marketing email, managed-checkout promo code or completed sale.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: campaign.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [ "name: string (required)", "description: string", "status: draft | requested | approved | active | paused | ended | settled | disputed | cancelled", "startAt: string,null", "endAt: string,null", "currency: string", "notes: string", "relationshipProductId: integer", "productId: integer", "approved_sale_price_cents: integer", "commercialModel: string", "wholesale_rate_cents: integer", "commissionRateBps: integer", "developerRevenueShareBps: integer", "licenseCap: integer,null" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "requested", "approved", "active", "paused", "ended", "settled", "disputed", "cancelled" ] }, "startAt": { "type": [ "string", "null" ], "format": "date-time" }, "endAt": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "notes": { "type": "string" }, "relationshipProductId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "approved_sale_price_cents": { "type": "integer" }, "commercialModel": { "type": "string" }, "wholesale_rate_cents": { "type": "integer" }, "commissionRateBps": { "type": "integer" }, "developerRevenueShareBps": { "type": "integer" }, "licenseCap": { "type": [ "integer", "null" ] } }, "required": [ "name" ], "additionalProperties": true } } } } } }, "/api/developer/partners/resellers/{relationshipId}/conversations/{threadId}/messages": { "get": { "summary": "Read messages in an owned relationship thread", "description": "partners.view and all-products workspace scope. Relationship and product ownership checks still apply. The thread must belong to this relationship. Message pages are returned in chronological display order.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: thread, messages, has_more, limit, offset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "thread": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope.", "x-request-fields": [ "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] }, "post": { "summary": "Reply to an owned relationship thread", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [ "body: string", "message: string", "attachments: array", "internal_note: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "message": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "internal_note": { "type": "boolean" } }, "additionalProperties": true, "anyOf": [ { "required": [ "body" ] }, { "required": [ "message" ] } ] } } } } } }, "/api/developer/partners/resellers/{relationshipId}/deny": { "post": { "summary": "Deny a reseller request", "description": "partners.view and all-products workspace scope. Writes additionally require partners.manage. Relationship and product ownership checks still apply. The current request side and status must allow this decision. Re-read state after a conflict.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope. Writes additionally require partners.manage.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/partners/resellers/{relationshipId}/end": { "post": { "summary": "End the supported relationship", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Changes relationship state. It does not refund external payments or erase historical orders and required accounting.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/resellers/{relationshipId}/licenses": { "get": { "summary": "Read paginated relationship licenses", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Default limit 100; can include usable serials and customer identity. Preserve exact bigint IDs, which may arrive as decimal strings.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: licenses, has_more, limit, offset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "licenses": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [ "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/resellers/{relationshipId}/suspend": { "post": { "summary": "Suspend the supported relationship", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Changes relationship state. It does not refund external payments or erase historical orders and required accounting.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/resellers/{relationshipId}/terms": { "patch": { "summary": "Save relationship commercial and visibility terms", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply. Supported snake-case aliases include commercial_model, default_commission_rate_bps, default_developer_revenue_share_bps, payment_terms, default_refund_policy, customer_visibility_mode, api_enabled, manual_issue_enabled, static_serial_export_enabled and monthly_license_cap. Share rates are basis points. PATCH /{relationshipId}/settings and /resellers/{relationshipId}/settings are aliases. Changes are real commercial settings, not a preview; they do not enable a platform financial flag or prove a payment.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [ "displayName: string", "display_name: string,null", "currency: string", "default_currency: string", "commercialModel: string", "default_wholesale_rate_cents: integer", "wholesale_rate: number", "commissionRateBps: integer", "developerRevenueShareBps: integer", "paymentTerms: string", "refundPolicy: string", "customerVisibilityMode: string", "apiEnabled: boolean", "manualIssueEnabled: boolean", "staticSerialExportEnabled: boolean", "monthlyLicenseCap: integer,null", "statementCycle: string", "termStatus: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "default_currency": { "type": "string" }, "commercialModel": { "type": "string" }, "default_wholesale_rate_cents": { "type": "integer" }, "wholesale_rate": { "type": "number" }, "commissionRateBps": { "type": "integer" }, "developerRevenueShareBps": { "type": "integer" }, "paymentTerms": { "type": "string" }, "refundPolicy": { "type": "string" }, "customerVisibilityMode": { "type": "string" }, "apiEnabled": { "type": "boolean" }, "manualIssueEnabled": { "type": "boolean" }, "staticSerialExportEnabled": { "type": "boolean" }, "monthlyLicenseCap": { "type": [ "integer", "null" ] }, "statementCycle": { "type": "string" }, "termStatus": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/partners/resellers/{relationshipId}/woocommerce-stores": { "get": { "summary": "List related store connections", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "relationship_id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string" }, "environment": { "type": "string" }, "display_name": { "type": "string" }, "base_url": { "type": "string" }, "status": { "type": "string" }, "connected_at": { "type": [ "string", "null" ], "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_catalog_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_webhook_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error_code": { "type": [ "string", "null" ] }, "last_error_message": { "type": [ "string", "null" ] } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "services/partnerWooCommerceService.js" ] } }, "/api/developer/partners/resellers/{relationshipId}/woocommerce-stores/{connectionId}": { "get": { "summary": "Inspect connection and catalog review", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: connection, catalog, products, total, offset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "relationship_id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string" }, "environment": { "type": "string" }, "display_name": { "type": "string" }, "base_url": { "type": "string" }, "status": { "type": "string" }, "connected_at": { "type": [ "string", "null" ], "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_catalog_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_webhook_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error_code": { "type": [ "string", "null" ] }, "last_error_message": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "catalog": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "total": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query status: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "services/partnerWooCommerceService.js" ] } }, "/api/developer/partners/resellers/{relationshipId}/woocommerce-stores/{connectionId}/activate": { "post": { "summary": "Activate the reviewed connection", "description": "Requires active relationship/API permission, authorized/synced store, complete confirmed mappings and healthy webhooks. Does not make SoundSync the seller of externally collected payments.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "relationship_id": { "type": "integer", "minimum": 1 }, "provider": { "type": "string" }, "environment": { "type": "string" }, "display_name": { "type": "string" }, "base_url": { "type": "string" }, "status": { "type": "string" }, "connected_at": { "type": [ "string", "null" ], "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_catalog_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_webhook_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error_code": { "type": [ "string", "null" ] }, "last_error_message": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "services/partnerWooCommerceService.js" ] } }, "/api/developer/partners/resellers/{relationshipId}/woocommerce-stores/{connectionId}/catalog/{catalogItemId}/mappings": { "delete": { "summary": "Remove a mapping", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "catalogItemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: catalog_item_id, removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalog_item_id": { "type": "integer", "minimum": 1 }, "removed": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "services/partnerWooCommerceService.js" ] }, "put": { "summary": "Approve/update a product mapping", "description": "Targets must be distinct approved API-fulfillment products. Revenue allocations total 10000 basis points; exact-only confirmation rejects candidates needing individual review.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "catalogItemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: mapped, revision, target_count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mapped": { "type": "boolean" }, "revision": { "type": "integer" }, "target_count": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "targets: array (required)", "requireExact: boolean", "all_variations: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "services/partnerWooCommerceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "properties": { "soundsync_product_id": { "type": "integer", "minimum": 1 }, "component_quantity": { "type": "integer", "minimum": 1 }, "revenue_allocation_bps": { "type": "integer" } }, "additionalProperties": true } }, "requireExact": { "type": "boolean" }, "all_variations": { "type": "boolean" } }, "required": [ "targets" ], "additionalProperties": true } } } } } }, "/api/developer/partners/resellers/{relationshipId}/woocommerce-stores/{connectionId}/catalog/{catalogItemId}/suggestion": { "post": { "summary": "Review the suggested mapping", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "catalogItemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: catalog_item_id, suggestion_dismissed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalog_item_id": { "type": "integer", "minimum": 1 }, "suggestion_dismissed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "dismissed: boolean (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "services/partnerWooCommerceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dismissed": { "type": "boolean" } }, "required": [ "dismissed" ], "additionalProperties": true } } } } } }, "/api/developer/partners/resellers/{relationshipId}/woocommerce-stores/{connectionId}/confirm-exact-mappings": { "post": { "summary": "Confirm the supported exact-match review", "description": "Bulk-confirms only exact eligible suggestions. Inspect failures; this does not approve ambiguous matches.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: mapped, failures.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mapped": { "type": "integer" }, "failures": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "services/partnerWooCommerceService.js" ] } }, "/api/developer/partners/sales-analytics": { "get": { "summary": "Read current-month reseller reporting by currency", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: period, currencies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "const": "current_month" }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "order_count": { "type": "integer" }, "gross_product_cents": { "type": "number" }, "refunded_line_cents": { "type": "number" }, "net_product_cents": { "type": "number" }, "developer_receivable_cents": { "type": "number" }, "reseller_remainder_cents": { "type": "number" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/partners/serial-pools": { "get": { "summary": "Read serial pools across owned relationships", "description": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: pools.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pools": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.view and all-products workspace scope; writes additionally require partners.manage. Owned relationship checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] } }, "/api/developer/plugin-connections/products/{productId}/status": { "get": { "summary": "Read product connection and licensing evidence", "description": "Reads Test Connection history and server-recorded successful activation/validation events. Runtime evidence must match the owning product/developer and an active, non-revoked product credential. connected means eligible success within the past 24 hours with that credential, not continuous availability. Explicitly non-production activity is excluded; existing server-side licensing events without environment are recognized, while manual tests require production/live. recentRuntimeSuccess distinguishes a licensing success from a connection test. setupVerified is historical integration evidence for the current credential, including non-production tests; it is not live health. Historical, revoked/replaced-credential, future-dated and missing records cannot claim current health. Missing history for a published product is informational, not a failure or readiness penalty. Customer-specific validation failures do not establish a platform outage.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: ok, productId, connected, status, lastSeenAt, lastSuccessAt, pluginVersion, environment, credentialId, errorCode, errorReason, evidenceState, evidenceSource, setupVerified, recentRuntimeSuccess, currentCredential, historicalSuccess, recentWindowHours, healthStatus, message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "productId": { "type": "string" }, "connected": { "type": "boolean" }, "status": { "type": "string" }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" }, "pluginVersion": { "type": [ "string", "null" ] }, "environment": { "type": [ "string", "null" ] }, "credentialId": { "type": [ "string", "null" ] }, "errorCode": { "type": [ "string", "null" ] }, "errorReason": { "type": [ "string", "null" ] }, "evidenceState": { "type": "string", "enum": [ "not_recorded", "credential_unverified", "recent_runtime", "recent_test", "historical" ] }, "evidenceSource": { "type": [ "string", "null" ] }, "setupVerified": { "type": "boolean" }, "recentRuntimeSuccess": { "type": "boolean" }, "currentCredential": { "type": "boolean" }, "historicalSuccess": { "type": "boolean" }, "recentWindowHours": { "type": "integer" }, "healthStatus": { "type": "string", "enum": [ "recent_success", "unknown" ] }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "credentials.view and assigned-product access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPluginConnectionRoutes.js", "controllers/developerPluginConnectionController.js", "services/pluginConnectionStatusService.js" ] } }, "/api/developer/plugin-keys/products": { "get": { "summary": "List product-scoped plugin credentials visible to the authenticated developer, optionally filtered by productId.", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-credentials" }, "parameters": [ { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "ok, credentials[], count. Credential records include appId, pluginKeyPreview, pluginSecretPreview, apiBaseUrl, status, isActive, lastUsedAt, rotated/revoked metadata, and one-time reveal metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "credentials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product credential management. Admin users may have broader operator visibility according to backend ownership checks.", "x-request-fields": [ "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "controllers/devPluginKeysController.js", "services/productPluginCredentialService.js" ] } }, "/api/developer/plugin-keys/products/{productId}": { "get": { "summary": "Fetch the active product credential/status for one developer-owned product.", "description": "Side effects: None.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-credentials" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok, credential, status/active state, credential previews and metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "created": { "type": "boolean" }, "rotated": { "type": "boolean" }, "revoked": { "type": "boolean" }, "previous_credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "one_time_reveal": { "type": "object", "properties": { "appId": { "type": "string" }, "pluginKey": { "type": "string" }, "pluginSecret": { "type": "string" }, "productKey": { "type": "string" }, "productSecret": { "type": "string" } }, "additionalProperties": true }, "secret_shown_once": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product credential management. Admin users may have broader operator visibility according to backend ownership checks.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "controllers/devPluginKeysController.js", "services/productPluginCredentialService.js" ] }, "post": { "summary": "Create the first active product credential for a product.", "description": "If an active credential already exists, the backend returns ACTIVE_CREDENTIAL_EXISTS with HTTP 409. Use ensure or rotate intentionally instead. Save newly returned secret material privately; ordinary reads return previews, not reusable secret reveal. Side effects: Inserts a product credential row with hashed key/secret and recoverable secret ciphertext when the runtime key is available.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-credentials" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "201 ok, credential, created true, one_time_reveal with appId, pluginKey, pluginSecret, and secret_shown_once true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "created": { "type": "boolean" }, "rotated": { "type": "boolean" }, "revoked": { "type": "boolean" }, "previous_credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "one_time_reveal": { "type": "object", "properties": { "appId": { "type": "string" }, "pluginKey": { "type": "string" }, "pluginSecret": { "type": "string" }, "productKey": { "type": "string" }, "productSecret": { "type": "string" } }, "additionalProperties": true }, "secret_shown_once": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product credential management. Admin users may have broader operator visibility according to backend ownership checks.", "x-request-fields": [ "reason: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "controllers/devPluginKeysController.js", "services/productPluginCredentialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/plugin-keys/products/{productId}/ensure": { "post": { "summary": "Return the current active credential, or create one if missing.", "description": "Creates only when needed. An existing credential response contains previews; handle rotationRequired rather than rotating a distributed product automatically. Side effects: May create a credential when none exists.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-credentials" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok, credential and created flag. New credentials include one_time_reveal; existing credentials return previews only.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "created": { "type": "boolean" }, "rotated": { "type": "boolean" }, "revoked": { "type": "boolean" }, "previous_credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "one_time_reveal": { "type": "object", "properties": { "appId": { "type": "string" }, "pluginKey": { "type": "string" }, "pluginSecret": { "type": "string" }, "productKey": { "type": "string" }, "productSecret": { "type": "string" } }, "additionalProperties": true }, "secret_shown_once": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product credential management. Admin users may have broader operator visibility according to backend ownership checks.", "x-request-fields": [ "reason: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "controllers/devPluginKeysController.js", "services/productPluginCredentialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/plugin-keys/products/{productId}/reveal-secret": { "post": { "summary": "Reveal a recoverable active credential secret to an authenticated product owner.", "description": "Older unrecoverable credentials return PRODUCT_CREDENTIAL_SECRET_UNAVAILABLE with rotate-key and rotate-secret recovery endpoints. Only a permitted one-time reveal is allowed. If the secret has already been consumed, coordinate deliberate credential rotation. Side effects: Records explicit reveal intent through controller/service metadata.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-credentials" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok, one_time_reveal/revealed credential material with appId, pluginKey, pluginSecret, and productKey/ProductSecret compatibility aliases.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "created": { "type": "boolean" }, "rotated": { "type": "boolean" }, "revoked": { "type": "boolean" }, "previous_credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "one_time_reveal": { "type": "object", "properties": { "appId": { "type": "string" }, "pluginKey": { "type": "string" }, "pluginSecret": { "type": "string" }, "productKey": { "type": "string" }, "productSecret": { "type": "string" } }, "additionalProperties": true }, "secret_shown_once": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product credential management. Admin users may have broader operator visibility according to backend ownership checks.", "x-request-fields": [ "reason: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "controllers/devPluginKeysController.js", "services/productPluginCredentialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/plugin-keys/products/{productId}/revoke": { "post": { "summary": "Revoke the active product credential for a product.", "description": "Revocation can affect installed clients. This call does not refund sales or delete ownership. Side effects: Marks the active credential inactive/revoked. Existing packages using that credential should fail Test Connection or product credential auth until regenerated with a new active credential.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-credentials" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok, revoked true/false and credential status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "created": { "type": "boolean" }, "rotated": { "type": "boolean" }, "revoked": { "type": "boolean" }, "previous_credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "one_time_reveal": { "type": "object", "properties": { "appId": { "type": "string" }, "pluginKey": { "type": "string" }, "pluginSecret": { "type": "string" }, "productKey": { "type": "string" }, "productSecret": { "type": "string" } }, "additionalProperties": true }, "secret_shown_once": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product credential management. Admin users may have broader operator visibility according to backend ownership checks.", "x-request-fields": [ "reason: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "controllers/devPluginKeysController.js", "services/productPluginCredentialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/plugin-keys/products/{productId}/rotate-key": { "post": { "summary": "Rotate the active product credential pair when a package or integration key needs replacement.", "description": "Rotates the active credential pair; coordinate existing binaries before invoking. Not a harmless read or signed-download refresh. Side effects: Revokes the previous active credential and inserts a replacement credential. Regenerate packages after this.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-credentials" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "201 ok, credential, one_time_reveal, previous_credential, rotated true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "created": { "type": "boolean" }, "rotated": { "type": "boolean" }, "revoked": { "type": "boolean" }, "previous_credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "one_time_reveal": { "type": "object", "properties": { "appId": { "type": "string" }, "pluginKey": { "type": "string" }, "pluginSecret": { "type": "string" }, "productKey": { "type": "string" }, "productSecret": { "type": "string" } }, "additionalProperties": true }, "secret_shown_once": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product credential management. Admin users may have broader operator visibility according to backend ownership checks.", "x-request-fields": [ "reason: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "controllers/devPluginKeysController.js", "services/productPluginCredentialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/plugin-keys/products/{productId}/rotate-secret": { "post": { "summary": "Rotate the active product credential pair when the secret is exposed, lost, or unrecoverable.", "description": "Rotates the active credential pair; coordinate existing binaries before invoking. Not a harmless read or signed-download refresh. Side effects: Revokes the previous active credential and inserts a replacement credential. The current implementation replaces the pair for both key and secret rotation.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-credentials" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "201 ok, credential, one_time_reveal, previous_credential, rotated true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "created": { "type": "boolean" }, "rotated": { "type": "boolean" }, "revoked": { "type": "boolean" }, "previous_credential": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKeyPreview": { "type": "string" }, "pluginSecretPreview": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "status": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretShownOnce": { "type": "boolean" } }, "additionalProperties": true }, "one_time_reveal": { "type": "object", "properties": { "appId": { "type": "string" }, "pluginKey": { "type": "string" }, "pluginSecret": { "type": "string" }, "productKey": { "type": "string" }, "productSecret": { "type": "string" } }, "additionalProperties": true }, "secret_shown_once": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product credential management. Admin users may have broader operator visibility according to backend ownership checks.", "x-request-fields": [ "reason: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "controllers/devPluginKeysController.js", "services/productPluginCredentialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/product-relationships": { "post": { "summary": "Create a same-developer parent/expansion relationship", "description": "expansion_requires_parent is the default and requires parentProductId. Standalone relationships can omit the parent. Snake_case aliases are accepted. Duplicate active relationships return 409; self/circular relationships are rejected.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/expansions" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: relationship, created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "parentProductId": { "type": [ "integer", "null" ] }, "childProductId": { "type": "integer", "minimum": 1 }, "relationshipType": { "type": "string", "enum": [ "expansion_requires_parent", "expansion_standalone" ] }, "status": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "created": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owner/admin product-management surface. Both parent and child must belong to the same developer. Do not assume these compatibility handlers support every delegated team role.", "x-request-fields": [ "parentProductId: integer,null", "parent_product_id: integer,null", "childProductId: integer", "child_product_id: integer", "relationshipType: expansion_requires_parent | expansion_standalone", "relationship_type: expansion_requires_parent | expansion_standalone", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerExpansionRoutes.js", "services/expansionFoundationService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parentProductId": { "type": [ "integer", "null" ] }, "parent_product_id": { "type": [ "integer", "null" ] }, "childProductId": { "type": "integer", "minimum": 1 }, "child_product_id": { "type": "integer", "minimum": 1 }, "relationshipType": { "type": "string", "enum": [ "expansion_requires_parent", "expansion_standalone" ] }, "relationship_type": { "type": "string", "enum": [ "expansion_requires_parent", "expansion_standalone" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "anyOf": [ { "required": [ "childProductId" ] }, { "required": [ "child_product_id" ] } ] } } } } } }, "/api/developer/product-relationships/{relationshipId}": { "delete": { "summary": "Deactivate a relationship without deleting products", "description": "Removes the active requirement relationship, not the product, payment or previously issued order.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/expansions" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "parentProductId": { "type": [ "integer", "null" ] }, "childProductId": { "type": "integer", "minimum": 1 }, "relationshipType": { "type": "string", "enum": [ "expansion_requires_parent", "expansion_standalone" ] }, "status": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owner/admin product-management surface. Both parent and child must belong to the same developer. Do not assume these compatibility handlers support every delegated team role.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerExpansionRoutes.js", "services/expansionFoundationService.js" ] } }, "/api/developer/products/{productId}/activity": { "get": { "summary": "Read activity for an assigned product", "description": "Also ensures the product licensing-rule row. Customer identity requires customers.view; serials require serials.view; order IDs require orders.view; entitlement IDs require entitlements.view. Restricted fields are null. Opaque messages, actor details and nested metadata require all four record permissions plus refunds.view. Client query/body fields cannot grant permissions.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "developerId": { "type": "integer", "minimum": 1 }, "actorType": { "type": [ "string", "null" ] }, "actorUserId": { "type": [ "integer", "null" ] }, "customerId": { "type": [ "integer", "null" ] }, "customerEmail": { "type": [ "string", "null" ] }, "customerName": { "type": [ "string", "null" ] }, "productId": { "type": [ "integer", "null" ] }, "productName": { "type": [ "string", "null" ] }, "serialId": { "type": [ "integer", "null" ] }, "serialCode": { "type": [ "string", "null" ] }, "entitlementId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "orderId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "eventType": { "type": "string" }, "severity": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and assigned-product access.", "x-request-fields": [ "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js", "services/platformEventService.js" ] } }, "/api/developer/products/{productId}/dashboard": { "get": { "summary": "Read the product overview with permission-filtered aggregates", "description": "Check access first. Denied aggregates are not queried. Restricted performance has available:false/reason:permission_required; restricted reviews, file metadata and activity use empty arrays; hidden KPI counts are null, not zero. The nested product omits file URLs/counts and analytics fields when unauthorized. hisePackage/restApi are null without credentials.view; no dashboard credential provisioning is attempted for that caller. Credential responses contain previews, not a full secret. Versions remain product metadata available to products.view.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-dashboard" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: access, product, health, kpis, performance, reviewSummary, readiness, hisePackage, pluginConnectionStatus, restApi, files, versions, reviews, recentActivity, storefrontDestination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "object", "properties": { "analytics": { "type": "boolean" }, "reviews": { "type": "boolean" }, "files": { "type": "boolean" }, "credentials": { "type": "boolean" } }, "additionalProperties": true }, "product": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "health": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kpis": { "type": "object", "properties": { "customerCount": { "type": [ "number", "null" ] }, "orderCount": { "type": [ "number", "null" ] }, "downloadsTotal": { "type": [ "number", "null" ] }, "ratingAverage": { "type": [ "number", "null" ] }, "ratingCount": { "type": [ "number", "null" ] } }, "additionalProperties": true }, "performance": { "type": "object", "properties": { "available": { "type": "boolean" }, "reason": { "type": "string" }, "ranges": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true }, "reviewSummary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "hisePackage": { "type": [ "object", "null" ] }, "pluginConnectionStatus": { "type": [ "object", "null" ] }, "restApi": { "type": [ "object", "null" ], "properties": { "status": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": [ "string", "null" ] }, "productKey": { "type": [ "string", "null" ] }, "productKeyPreview": { "type": [ "string", "null" ] }, "environment": { "type": "string" }, "apiStatus": { "type": "string" }, "lastRequestAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretReturned": { "const": false } }, "additionalProperties": true }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "platform": { "type": "string" }, "type": { "type": "string" }, "sizeBytes": { "type": [ "number", "null" ] }, "version": { "type": [ "string", "null" ] }, "managed": { "type": "boolean" }, "deliveryMode": { "type": "string" }, "uploadedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "version": { "type": "string" }, "changelog": { "type": "string" }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time" }, "isCurrent": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "productId": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "customerEmail": { "type": [ "string", "null" ] }, "customerId": { "type": [ "integer", "null" ] }, "imported": { "type": "boolean" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "recentActivity": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "storefrontDestination": { "type": "object", "properties": { "url": { "type": "string" }, "kind": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "products.view and assigned-product access; analytics.view, reviews.view, product_files.view and credentials.view separately control optional fields.", "x-request-fields": [ "query currency: string", "query environment: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerProductDashboardRoutes.js", "controllers/developerProductDashboardController.js", "services/productDashboardService.js" ] } }, "/api/developer/products/{productId}/expansion": { "patch": { "summary": "Update expansion configuration", "description": "Supported snake_case aliases are accepted. Setting a parent can create a relationship. To remove an active relationship, use the relationship deletion endpoint and reload requirements; a parent field alone is not the complete relationship history.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/expansions" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: expansion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "expansion": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "productType": { "type": "string" }, "isExpansion": { "type": "boolean" }, "parentProductId": { "type": [ "integer", "null" ] }, "requiredParentProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "requiresParentEntitlement": { "type": "boolean" }, "grantsParentAccess": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "hidden" ] }, "expansionSortOrder": { "type": "integer" }, "expansionAccessState": { "type": "string" }, "expansionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "ownerUserId": { "type": "integer", "minimum": 1 }, "marketplaceVisible": { "type": "boolean" }, "isDraft": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owner/admin product-management surface. Both parent and child must belong to the same developer. Do not assume these compatibility handlers support every delegated team role.", "x-request-fields": [ "parentProductId: integer,null", "productType: string", "expansionVisibility: public | unlisted | hidden", "requiresParentEntitlement: boolean", "grantsParentAccess: boolean", "expansionSortOrder: integer", "expansionMetadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerExpansionRoutes.js", "services/expansionFoundationService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "parentProductId": { "type": [ "integer", "null" ] }, "productType": { "type": "string" }, "expansionVisibility": { "type": "string", "enum": [ "public", "unlisted", "hidden" ] }, "requiresParentEntitlement": { "type": "boolean" }, "grantsParentAccess": { "type": "boolean" }, "expansionSortOrder": { "type": "integer" }, "expansionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } }, "put": { "summary": "Update expansion configuration", "description": "Supported snake_case aliases are accepted. Setting a parent can create a relationship. To remove an active relationship, use the relationship deletion endpoint and reload requirements; a parent field alone is not the complete relationship history.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/expansions" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: expansion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "expansion": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "productType": { "type": "string" }, "isExpansion": { "type": "boolean" }, "parentProductId": { "type": [ "integer", "null" ] }, "requiredParentProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "requiresParentEntitlement": { "type": "boolean" }, "grantsParentAccess": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "hidden" ] }, "expansionSortOrder": { "type": "integer" }, "expansionAccessState": { "type": "string" }, "expansionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "ownerUserId": { "type": "integer", "minimum": 1 }, "marketplaceVisible": { "type": "boolean" }, "isDraft": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owner/admin product-management surface. Both parent and child must belong to the same developer. Do not assume these compatibility handlers support every delegated team role.", "x-request-fields": [ "parentProductId: integer,null", "productType: string", "expansionVisibility: public | unlisted | hidden", "requiresParentEntitlement: boolean", "grantsParentAccess: boolean", "expansionSortOrder: integer", "expansionMetadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerExpansionRoutes.js", "services/expansionFoundationService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "parentProductId": { "type": [ "integer", "null" ] }, "productType": { "type": "string" }, "expansionVisibility": { "type": "string", "enum": [ "public", "unlisted", "hidden" ] }, "requiresParentEntitlement": { "type": "boolean" }, "grantsParentAccess": { "type": "boolean" }, "expansionSortOrder": { "type": "integer" }, "expansionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/expansions": { "get": { "summary": "List linked expansion products", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/expansions" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: parent, expansions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "parent": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "productType": { "type": "string" }, "isExpansion": { "type": "boolean" }, "parentProductId": { "type": [ "integer", "null" ] }, "requiredParentProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "requiresParentEntitlement": { "type": "boolean" }, "grantsParentAccess": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "hidden" ] }, "expansionSortOrder": { "type": "integer" }, "expansionAccessState": { "type": "string" }, "expansionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "ownerUserId": { "type": "integer", "minimum": 1 }, "marketplaceVisible": { "type": "boolean" }, "isDraft": { "type": "boolean" } }, "additionalProperties": true }, "expansions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "productType": { "type": "string" }, "isExpansion": { "type": "boolean" }, "parentProductId": { "type": [ "integer", "null" ] }, "requiredParentProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "requiresParentEntitlement": { "type": "boolean" }, "grantsParentAccess": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "hidden" ] }, "expansionSortOrder": { "type": "integer" }, "expansionAccessState": { "type": "string" }, "expansionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "ownerUserId": { "type": "integer", "minimum": 1 }, "marketplaceVisible": { "type": "boolean" }, "isDraft": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owner/admin product-management surface. Both parent and child must belong to the same developer. Do not assume these compatibility handlers support every delegated team role.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerExpansionRoutes.js", "services/expansionFoundationService.js" ] }, "post": { "summary": "Link an existing expansion to this parent", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/expansions" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: expansion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "expansion": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "productType": { "type": "string" }, "isExpansion": { "type": "boolean" }, "parentProductId": { "type": [ "integer", "null" ] }, "requiredParentProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "requiresParentEntitlement": { "type": "boolean" }, "grantsParentAccess": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "hidden" ] }, "expansionSortOrder": { "type": "integer" }, "expansionAccessState": { "type": "string" }, "expansionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "ownerUserId": { "type": "integer", "minimum": 1 }, "marketplaceVisible": { "type": "boolean" }, "isDraft": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owner/admin product-management surface. Both parent and child must belong to the same developer. Do not assume these compatibility handlers support every delegated team role.", "x-request-fields": [ "parentProductId: integer,null", "productType: string", "expansionVisibility: public | unlisted | hidden", "requiresParentEntitlement: boolean", "grantsParentAccess: boolean", "expansionSortOrder: integer", "expansionMetadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "expansionProductId: integer", "expansion_product_id: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerExpansionRoutes.js", "services/expansionFoundationService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parentProductId": { "type": [ "integer", "null" ] }, "productType": { "type": "string" }, "expansionVisibility": { "type": "string", "enum": [ "public", "unlisted", "hidden" ] }, "requiresParentEntitlement": { "type": "boolean" }, "grantsParentAccess": { "type": "boolean" }, "expansionSortOrder": { "type": "integer" }, "expansionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "expansionProductId": { "type": "integer", "minimum": 1 }, "expansion_product_id": { "type": "integer", "minimum": 1 } }, "additionalProperties": true, "anyOf": [ { "required": [ "expansionProductId" ] }, { "required": [ "expansion_product_id" ] } ] } } } } } }, "/api/developer/products/{productId}/file-versions": { "get": { "summary": "List versioned delivery metadata", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "productId": { "type": "integer", "minimum": 1 }, "version": { "type": "string" }, "releaseTitle": { "type": [ "string", "null" ] }, "releaseNotes": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isLatest": { "type": "boolean" }, "published": { "type": "boolean" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "fileName": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "fileKey": { "type": [ "string", "null" ] }, "fileSize": { "type": [ "number", "string", "null" ] }, "mimeType": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "sortOrder": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "product_files.view and assigned-product access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ] }, "post": { "summary": "Create versioned delivery metadata", "description": "Returns the refreshed version list, not a single version. isActive and published default true; isLatest defaults false. Making a version latest clears the previous latest within this product. Asset entries are metadata, not an upload or proof that a URL is safe or publicly accessible. Use the upload workflow first and do not publish private storage keys.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "productId": { "type": "integer", "minimum": 1 }, "version": { "type": "string" }, "releaseTitle": { "type": [ "string", "null" ] }, "releaseNotes": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isLatest": { "type": "boolean" }, "published": { "type": "boolean" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "fileName": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "fileKey": { "type": [ "string", "null" ] }, "fileSize": { "type": [ "number", "string", "null" ] }, "mimeType": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "sortOrder": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "product_files.manage and assigned-product access.", "x-request-fields": [ "version: string (required)", "releaseTitle: string", "releaseNotes: string", "isActive: boolean", "isLatest: boolean", "published: boolean", "assets: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "releaseTitle": { "type": "string" }, "releaseNotes": { "type": "string" }, "isActive": { "type": "boolean" }, "isLatest": { "type": "boolean" }, "published": { "type": "boolean" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "fileName": { "type": "string" }, "url": { "type": "string" }, "fileKey": { "type": "string" }, "fileSize": { "type": [ "number", "string", "null" ] }, "mimeType": { "type": "string" }, "platform": { "type": "string" }, "sortOrder": { "type": "integer" } }, "additionalProperties": true } } }, "required": [ "version" ], "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/file-versions/{versionId}/latest": { "post": { "summary": "Select the latest delivery version", "description": "The version must belong to this product/developer. Marks it active and clears other latest markers; does not upload files or change customer ownership.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "productId": { "type": "integer", "minimum": 1 }, "version": { "type": "string" }, "releaseTitle": { "type": [ "string", "null" ] }, "releaseNotes": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isLatest": { "type": "boolean" }, "published": { "type": "boolean" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "fileName": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "fileKey": { "type": [ "string", "null" ] }, "fileSize": { "type": [ "number", "string", "null" ] }, "mimeType": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "sortOrder": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "product_files.manage and assigned-product access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ] } }, "/api/developer/products/{productId}/files": { "get": { "summary": "Read dashboard delivery-file metadata", "description": "Metadata only, not a signed download grant. Use the managed upload and authorized delivery workflows for file contents.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-dashboard" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "platform": { "type": "string" }, "type": { "type": "string" }, "sizeBytes": { "type": [ "number", "null" ] }, "version": { "type": [ "string", "null" ] }, "managed": { "type": "boolean" }, "deliveryMode": { "type": "string" }, "uploadedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "product_files.view and assigned-product access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerProductDashboardRoutes.js", "controllers/developerProductDashboardController.js", "services/productDashboardService.js" ] } }, "/api/developer/products/{productId}/hise-package": { "get": { "summary": "Generate or retrieve the chosen product package", "description": "Can provision/recover the product credential, prepare private storage, and record package activity. Do not use as an unattended polling request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/hise-packages" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "variant", "in": "query", "required": false, "schema": { "enum": [ "hisescript", "native" ] } }, { "name": "experienceMode", "in": "query", "required": false, "schema": { "enum": [ "validation-only", "storefront-only", "storefront-validation" ] } }, { "name": "uiWidth", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "uiHeight", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "releaseChannel", "in": "query", "required": false, "schema": { "const": "stable" } } ], "responses": { "200": { "description": "200 JSON { url, filename, expiresIn: 300 }, not ZIP bytes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "expiresIn": { "const": 300 } }, "required": [ "url", "filename", "expiresIn" ], "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "product_files.view and access to the product.", "x-request-fields": [ "query variant: value", "query experienceMode: value", "query uiWidth: integer", "query uiHeight: integer", "query releaseChannel: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerHisePackageRoutes.js", "controllers/developerHisePackageController.js" ] } }, "/api/developer/products/{productId}/hise-package/generate": { "post": { "summary": "Generate a package from current saved settings", "description": "Same package response as download; generating a package does not publish or rebuild the plugin.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/hise-packages" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 JSON { url, filename, expiresIn: 300 }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "expiresIn": { "const": 300 } }, "required": [ "url", "filename", "expiresIn" ], "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "product_files.manage and access to the product.", "x-request-fields": [ "variant: hisescript | native", "experienceMode: validation-only | storefront-only | storefront-validation", "uiWidth: integer", "uiHeight: integer", "releaseChannel: \"stable\"" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerHisePackageRoutes.js", "controllers/developerHisePackageController.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant": { "enum": [ "hisescript", "native" ] }, "experienceMode": { "enum": [ "validation-only", "storefront-only", "storefront-validation" ] }, "uiWidth": { "type": "integer", "minimum": 1 }, "uiHeight": { "type": "integer", "minimum": 1 }, "releaseChannel": { "const": "stable" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/hise-package/regenerate": { "post": { "summary": "Regenerate with credential rotation", "description": "Rotates the product credential. Coordinate existing installed clients before calling; this is not the way to refresh an expired download URL.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/hise-packages" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 JSON { url, filename, expiresIn: 300 }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "expiresIn": { "const": 300 } }, "required": [ "url", "filename", "expiresIn" ], "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "product_files.manage and access to the product.", "x-request-fields": [ "variant: hisescript | native", "experienceMode: validation-only | storefront-only | storefront-validation", "uiWidth: integer", "uiHeight: integer", "releaseChannel: \"stable\"" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerHisePackageRoutes.js", "controllers/developerHisePackageController.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant": { "enum": [ "hisescript", "native" ] }, "experienceMode": { "enum": [ "validation-only", "storefront-only", "storefront-validation" ] }, "uiWidth": { "type": "integer", "minimum": 1 }, "uiHeight": { "type": "integer", "minimum": 1 }, "releaseChannel": { "const": "stable" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/hise-package/status": { "get": { "summary": "Read product package readiness metadata", "description": "credentialStatus is a structured status object, not a string or full secret. This compatible status handler can ensure product package credentials; it is not a zero-write health check. Package-ready metadata is not a new HISE runtime attestation.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-dashboard" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: credentialStatus, status, packageReady, lastGeneratedAt, lastPluginConnectionAt, supportedModes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credentialStatus": { "type": "object", "properties": { "status": { "type": "string" }, "ready": { "type": "boolean" }, "isActive": { "type": "boolean" }, "appId": { "type": [ "string", "null" ] }, "productKeyPreview": { "type": [ "string", "null" ] }, "created": { "type": "boolean" }, "skipped": { "type": "boolean" } }, "additionalProperties": true }, "status": { "type": "string" }, "packageReady": { "type": "boolean" }, "lastGeneratedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastPluginConnectionAt": { "type": [ "string", "null" ], "format": "date-time" }, "supportedModes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "products.view and assigned-product access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerProductDashboardRoutes.js", "controllers/developerProductDashboardController.js", "services/productDashboardService.js" ] } }, "/api/developer/products/{productId}/juce-package": { "get": { "summary": "Prepare the product source package and return a private download link", "description": "Prepares or reuses a product-specific source ZIP and returns a private download link valid for 300 seconds; it is not metadata-only inspection or a read-only health check. All package-link routes can provision or recover product credentials and record package/download activity. GET and download aliases require product_files.view; POST /generate requires product_files.manage. Product assignment and package-channel access also apply. Keep the account token and returned link private. A regenerated package does not update compiled customer plugins: rebuild, test and redistribute. See /docs/juce/package-updates for signed offline-grace readiness and upgrade steps.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": false, "schema": { "enum": [ "windows", "macos" ] } }, { "name": "releaseChannel", "in": "query", "required": false, "schema": { "const": "stable" } } ], "responses": { "200": { "description": "HTTP 200: url, filename, expiresIn.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "expiresIn": { "const": 300 } }, "required": [ "url", "filename", "expiresIn" ], "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "query platform: value", "query releaseChannel: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerJucePackageRoutes.js", "controllers/developerJucePackageController.js" ] } }, "/api/developer/products/{productId}/juce-package/download": { "get": { "summary": "Download the product package", "description": "Prepares or reuses a product-specific source ZIP and returns a private download link valid for 300 seconds; it is not metadata-only inspection or a read-only health check. All package-link routes can provision or recover product credentials and record package/download activity. GET and download aliases require product_files.view; POST /generate requires product_files.manage. Product assignment and package-channel access also apply. Keep the account token and returned link private. A regenerated package does not update compiled customer plugins: rebuild, test and redistribute. See /docs/juce/package-updates for signed offline-grace readiness and upgrade steps.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": false, "schema": { "enum": [ "windows", "macos" ] } }, { "name": "releaseChannel", "in": "query", "required": false, "schema": { "const": "stable" } } ], "responses": { "200": { "description": "HTTP 200: url, filename, expiresIn.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "expiresIn": { "const": 300 } }, "required": [ "url", "filename", "expiresIn" ], "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "query platform: value", "query releaseChannel: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerJucePackageRoutes.js", "controllers/developerJucePackageController.js" ] }, "post": { "summary": "Retrieve through the compatible download route", "description": "Prepares or reuses a product-specific source ZIP and returns a private download link valid for 300 seconds; it is not metadata-only inspection or a read-only health check. All package-link routes can provision or recover product credentials and record package/download activity. GET and download aliases require product_files.view; POST /generate requires product_files.manage. Product assignment and package-channel access also apply. Keep the account token and returned link private. A regenerated package does not update compiled customer plugins: rebuild, test and redistribute. See /docs/juce/package-updates for signed offline-grace readiness and upgrade steps.", "externalDocs": { "url": "https://www.soundsync.dev/docs/juce-package" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 JSON { url, filename, expiresIn: 300 }. This route delegates to the maintained source-package workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "expiresIn": { "const": 300 } }, "required": [ "url", "filename", "expiresIn" ], "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "platform: windows | macos", "releaseChannel: \"stable\"" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerJucePackageRoutes.js", "controllers/developerJucePackageController.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "enum": [ "windows", "macos" ] }, "releaseChannel": { "const": "stable" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/juce-package/generate": { "post": { "summary": "Generate the product-specific package", "description": "Prepares or reuses a product-specific source ZIP and returns a private download link valid for 300 seconds; it is not metadata-only inspection or a read-only health check. All package-link routes can provision or recover product credentials and record package/download activity. GET and download aliases require product_files.view; POST /generate requires product_files.manage. Product assignment and package-channel access also apply. Keep the account token and returned link private. A regenerated package does not update compiled customer plugins: rebuild, test and redistribute. See /docs/juce/package-updates for signed offline-grace readiness and upgrade steps.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: url, filename, expiresIn.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "expiresIn": { "const": 300 } }, "required": [ "url", "filename", "expiresIn" ], "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "platform: windows | macos", "releaseChannel: \"stable\"" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerJucePackageRoutes.js", "controllers/developerJucePackageController.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "enum": [ "windows", "macos" ] }, "releaseChannel": { "const": "stable" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/licensing-rules": { "get": { "summary": "Read or initialize product licensing rules", "description": "This read upserts the product rule row and can initialize defaults. It is not a zero-write health check.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "developerId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "activationMode": { "type": "string", "enum": [ "serial_only", "email_entitlement", "serial_or_email" ] }, "offlineGraceEnabled": { "type": "boolean" }, "offlineGraceDays": { "type": "integer", "minimum": 0, "maximum": 90 }, "maxActivationsPerCustomer": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "allowCustomerSelfReset": { "type": "boolean" }, "resetCooldownDays": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365 }, "suspendedLicenseBehavior": { "type": "string", "enum": [ "lock", "warning_only", "grace" ] }, "refundedOrderBehavior": { "type": "string", "enum": [ "revoke_immediately", "suspend", "manual_review" ] }, "failedValidationBehavior": { "type": "string", "enum": [ "show_activation_screen", "show_support_message", "lock" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "products.view and assigned-product access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ] }, "put": { "summary": "Save licensing rules and detect stale edits", "description": "Send the full intended rule set. Unlike a sparse PATCH, omitted fields normalize to service defaults: serial_or_email, offline grace enabled for 7 days, no explicit activation limit, self-reset off, reset cooldown 30 days, lock suspended licenses, immediate refund revocation and activation screen on failure. Snake_case field aliases are accepted. If expectedRules is supplied, include every current rule field; a mismatch returns 409 LICENSE_RULES_CHANGED. Stored rules do not prove every native runtime state has been exercised.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "developerId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "activationMode": { "type": "string", "enum": [ "serial_only", "email_entitlement", "serial_or_email" ] }, "offlineGraceEnabled": { "type": "boolean" }, "offlineGraceDays": { "type": "integer", "minimum": 0, "maximum": 90 }, "maxActivationsPerCustomer": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "allowCustomerSelfReset": { "type": "boolean" }, "resetCooldownDays": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365 }, "suspendedLicenseBehavior": { "type": "string", "enum": [ "lock", "warning_only", "grace" ] }, "refundedOrderBehavior": { "type": "string", "enum": [ "revoke_immediately", "suspend", "manual_review" ] }, "failedValidationBehavior": { "type": "string", "enum": [ "show_activation_screen", "show_support_message", "lock" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "products.edit and assigned-product access.", "x-request-fields": [ "activationMode: serial_only | email_entitlement | serial_or_email", "offlineGraceEnabled: boolean", "offlineGraceDays: integer", "maxActivationsPerCustomer: integer,null", "allowCustomerSelfReset: boolean", "resetCooldownDays: integer,null", "suspendedLicenseBehavior: lock | warning_only | grace", "refundedOrderBehavior: revoke_immediately | suspend | manual_review", "failedValidationBehavior: show_activation_screen | show_support_message | lock", "expectedRules: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "activationMode": { "type": "string", "enum": [ "serial_only", "email_entitlement", "serial_or_email" ] }, "offlineGraceEnabled": { "type": "boolean" }, "offlineGraceDays": { "type": "integer", "minimum": 0, "maximum": 90 }, "maxActivationsPerCustomer": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "allowCustomerSelfReset": { "type": "boolean" }, "resetCooldownDays": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365 }, "suspendedLicenseBehavior": { "type": "string", "enum": [ "lock", "warning_only", "grace" ] }, "refundedOrderBehavior": { "type": "string", "enum": [ "revoke_immediately", "suspend", "manual_review" ] }, "failedValidationBehavior": { "type": "string", "enum": [ "show_activation_screen", "show_support_message", "lock" ] }, "expectedRules": { "type": "object", "properties": { "activationMode": { "type": "string", "enum": [ "serial_only", "email_entitlement", "serial_or_email" ] }, "offlineGraceEnabled": { "type": "boolean" }, "offlineGraceDays": { "type": "integer", "minimum": 0, "maximum": 90 }, "maxActivationsPerCustomer": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "allowCustomerSelfReset": { "type": "boolean" }, "resetCooldownDays": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365 }, "suspendedLicenseBehavior": { "type": "string", "enum": [ "lock", "warning_only", "grace" ] }, "refundedOrderBehavior": { "type": "string", "enum": [ "revoke_immediately", "suspend", "manual_review" ] }, "failedValidationBehavior": { "type": "string", "enum": [ "show_activation_screen", "show_support_message", "lock" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets": { "get": { "summary": "Asset builder overview", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: productId, developerId, sourceAssetTypes, usageRoles, primaryRoles, presentationModes, placements, profile, assets, masks, duplicateGroups, generatedAssets, generatedAssetVersions, templates, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ] } }, "/api/developer/products/{productId}/marketplace-assets/ensure-core-set": { "post": { "summary": "Prepare the supported core placements", "description": "Prepares missing core placements and normally preserves active assets. force:true deliberately regenerates the requested set. sourceAssetId (or subjectAssetId) selects an owned usable source; an explicitly unavailable selection returns SOURCE_ASSET_REQUIRED rather than silently using a different upload. Without a usable source, MARKETPLACE_SOURCE_REQUIRED leaves the saved product unchanged. Core rendering resolves a compatible mode per placement: background_texture uses minimal_brand; other incompatible modes use a supported source-based recommendation. A single non-core incompatible render can return PLACEMENT_MODE_INCOMPATIBLE. Inspect generated[], jobs[], skippedPlacements and overview; this does not guarantee marketplace placement or publish the product.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "HTTP 202: ready, sourceAsset, generated, jobs, placements, skippedPlacements, overview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "sourceAsset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "generated": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "placementType": { "type": "string" }, "generatedAssetId": { "type": "integer", "minimum": 1 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "placements": { "type": "array", "items": { "type": "string" } }, "skippedPlacements": { "type": "array", "items": { "type": "string" } }, "overview": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "placementType: string", "placements: array", "presentationMode: string", "templateId: string", "subjectAssetId: integer", "sourceAssetId: integer", "profilePatch: object", "palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "idempotencyKey: string", "processSynchronously: boolean", "coreSet: boolean", "force: boolean", "autoSelectTemplate: boolean", "organizeExistingMedia: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "placementType": { "type": "string" }, "placements": { "type": "array", "items": { "type": "string" } }, "presentationMode": { "type": "string" }, "templateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "profilePatch": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "idempotencyKey": { "type": "string" }, "processSynchronously": { "type": "boolean" }, "coreSet": { "type": "boolean" }, "force": { "type": "boolean" }, "autoSelectTemplate": { "type": "boolean" }, "organizeExistingMedia": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/ensure/{placementType}": { "post": { "summary": "Prepare a particular placement", "description": "May reuse a valid asset or prepare a job. Do not infer a new render from every successful ensure call.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "placementType", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "HTTP 202: job, asset, created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "placementType": { "type": "string" }, "generatedAssetId": { "type": "integer", "minimum": 1 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "asset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "created": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "placementType: string", "placements: array", "presentationMode: string", "templateId: string", "subjectAssetId: integer", "sourceAssetId: integer", "profilePatch: object", "palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "idempotencyKey: string", "processSynchronously: boolean", "coreSet: boolean", "force: boolean", "autoSelectTemplate: boolean", "organizeExistingMedia: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "placementType": { "type": "string" }, "placements": { "type": "array", "items": { "type": "string" } }, "presentationMode": { "type": "string" }, "templateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "profilePatch": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "idempotencyKey": { "type": "string" }, "processSynchronously": { "type": "boolean" }, "coreSet": { "type": "boolean" }, "force": { "type": "boolean" }, "autoSelectTemplate": { "type": "boolean" }, "organizeExistingMedia": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/generated-assets/{assetId}": { "delete": { "summary": "Delete the selected generated asset", "description": "Default removal can archive rather than physically delete. Current artwork can be preserved. Inspect deleted, archived and storageDeleted separately.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: deleted, archived, skipped, preservedCurrent, assetId, asset, reason, storageDeleted, overview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "archived": { "type": "boolean" }, "skipped": { "type": "boolean" }, "preservedCurrent": { "type": "boolean" }, "assetId": { "type": "integer", "minimum": 1 }, "asset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "reason": { "type": "string" }, "storageDeleted": { "type": "boolean" }, "overview": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "preserveCurrent: boolean", "preserveActive: boolean", "permanent: boolean", "forcePermanent: boolean", "strictStorageDelete: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "preserveCurrent": { "type": "boolean" }, "preserveActive": { "type": "boolean" }, "permanent": { "type": "boolean" }, "forcePermanent": { "type": "boolean" }, "strictStorageDelete": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/generated-assets/{assetId}/approval": { "post": { "summary": "Change approval deliberately", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: asset, overview, autoGeneration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "overview": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "autoGeneration": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "status: string", "approvalStatus: string", "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalStatus": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/generated-assets/{assetId}/restore": { "post": { "summary": "Restore a generated asset", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: asset, overview, autoGeneration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "overview": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "autoGeneration": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/masks/{maskId}": { "patch": { "summary": "Save mask correction", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "maskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: mask, derivativeAsset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mask": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true }, "derivativeAsset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "crop: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "brushOperations: array", "threshold: number", "edgeFeather: number", "approvalState: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "brushOperations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" }, "approvalState": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/organize": { "post": { "summary": "Organize source assets", "description": "Organizes existing product assets; this can update source-asset records.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: productId, developerId, sourceAssetTypes, usageRoles, primaryRoles, presentationModes, placements, profile, assets, masks, duplicateGroups, generatedAssets, generatedAssetVersions, templates, readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ] } }, "/api/developer/products/{productId}/marketplace-assets/preview": { "get": { "summary": "Private placement preview", "description": "Private preview does not publish a product, reserve a marketplace placement or activate artwork.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "placementType", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "selectedAssetId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: preview, private, product, developer, selectedPlacement, selectedAssetId, assets, primaryAsset, generatedAssets, generatedAssetVersions, placements, profile, privatePreviewNotice.", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "boolean" }, "private": { "type": "boolean" }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true }, "developer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true }, "selectedPlacement": { "type": "string" }, "selectedAssetId": { "type": [ "integer", "null" ] }, "assets": { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "primaryAsset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "privatePreviewNotice": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query placementType: string", "query selectedAssetId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ] } }, "/api/developer/products/{productId}/marketplace-assets/preview/{placementType}": { "get": { "summary": "One private placement preview", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "placementType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "selectedAssetId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: asset, preview, private.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "preview": { "type": "boolean" }, "private": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query selectedAssetId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ] } }, "/api/developer/products/{productId}/marketplace-assets/profile": { "patch": { "summary": "Update placement profile", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: profile, overview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "overview": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "presentationMode: string", "visualDirection: string", "palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "selectedTemplateId: string", "subjectAssetId: integer", "settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/render-jobs": { "post": { "summary": "Queue a render or placement family", "description": "placements requests a family; a single placement creates one job. Inspect the job outcome; accepted is not published.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "HTTP 202: job, jobs, assets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "placementType": { "type": "string" }, "generatedAssetId": { "type": "integer", "minimum": 1 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "placementType": { "type": "string" }, "generatedAssetId": { "type": "integer", "minimum": 1 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "placementType: string", "placements: array", "presentationMode: string", "templateId: string", "subjectAssetId: integer", "sourceAssetId: integer", "profilePatch: object", "palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "idempotencyKey: string", "processSynchronously: boolean", "coreSet: boolean", "force: boolean", "autoSelectTemplate: boolean", "organizeExistingMedia: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "placementType": { "type": "string" }, "placements": { "type": "array", "items": { "type": "string" } }, "presentationMode": { "type": "string" }, "templateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "profilePatch": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "idempotencyKey": { "type": "string" }, "processSynchronously": { "type": "boolean" }, "coreSet": { "type": "boolean" }, "force": { "type": "boolean" }, "autoSelectTemplate": { "type": "boolean" }, "organizeExistingMedia": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/render-jobs/{jobId}": { "get": { "summary": "Inspect render progress/result", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "placementType": { "type": "string" }, "generatedAssetId": { "type": "integer", "minimum": 1 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ] } }, "/api/developer/products/{productId}/marketplace-assets/render-preview": { "post": { "summary": "Render a private image without saving", "description": "Requires products.view and assigned-product access. Renders a private draft image in memory; there is no render job, upload, saved profile change, activation or publication. Send one placementType (default standard_product_cover), not placements. sourceAssetId selects an owned usable source; settings and palette customize this draft. Snake-case placement_type/presentation_mode/source_asset_id/template_id aliases are accepted. Returns binary image/png or image/webp according to the placement, not JSON/base64. Cache-Control is private, no-store. Missing sources or unsupported placements are errors, not a reason to publish a fallback.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: review the response schema below.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "products.view and assigned-product access.", "x-request-fields": [ "placementType: string", "presentationMode: string", "templateId: string", "sourceAssetId: integer", "palette: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "settings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "placementType": { "type": "string" }, "presentationMode": { "type": "string" }, "templateId": { "type": "string" }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/replacements/{placementType}": { "post": { "summary": "Upload one custom replacement", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "placementType", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: asset, overview, autoGeneration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "overview": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "autoGeneration": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "file: string (required)", "active: string", "altText: string", "creatorType: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "active": { "type": "string" }, "altText": { "type": "string" }, "creatorType": { "type": "string" } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/source-assets": { "post": { "summary": "Upload guarded source images", "description": "Use repeated files fields (at most 12). autoGenerate is the multipart string true to request generation; upload success and generation success are separate.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: assets, autoGeneration, overview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "autoGeneration": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "overview": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "files: array (required)", "sourceClassification: string", "usageRoles: string", "primaryRole: string", "autoGenerate: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "string", "format": "binary" } }, "sourceClassification": { "type": "string" }, "usageRoles": { "type": "string" }, "primaryRole": { "type": "string" }, "autoGenerate": { "type": "string" } }, "required": [ "files" ], "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/source-assets/{assetId}": { "patch": { "summary": "Update source metadata", "description": "Updating source roles can queue core marketplace artwork. This is not only a label change.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: asset, overview, autoGeneration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "overview": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "sourceAssetTypes": { "type": "array", "items": { "type": "string" } }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRoles": { "type": "array", "items": { "type": "string" } }, "presentationModes": { "type": "array", "items": { "type": "string" } }, "placements": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "profile": { "type": "object", "properties": { "presentationMode": { "type": "string" }, "visualDirection": { "type": "string" }, "palette": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "selectedTemplateId": { "type": "string" }, "subjectAssetId": { "type": "integer", "minimum": 1 }, "settings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "masks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true } }, "duplicateGroups": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "generatedAssets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "generatedAssetVersions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "templates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "readiness": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "autoGeneration": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "sourceClassification: string", "classificationConfidence: string", "classificationReason: string", "usageRoles: array", "primaryRole: string", "archived: boolean", "reviewStatus: string", "developerConfirmedClassification: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "classificationReason": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": "string" }, "archived": { "type": "boolean" }, "reviewStatus": { "type": "string" }, "developerConfirmedClassification": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/marketplace-assets/source-assets/{assetId}/extraction": { "post": { "summary": "Request product-interface extraction", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: mask, derivativeAsset, fallbackRecommendation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mask": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sourceAssetId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "approvalState": { "type": "string" }, "crop": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "threshold": { "type": "number" }, "edgeFeather": { "type": "number" } }, "additionalProperties": true }, "derivativeAsset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true }, "fallbackRecommendation": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ] } }, "/api/developer/products/{productId}/marketplace-assets/templates": { "get": { "summary": "List supported templates", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "includeInactive", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: templates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "family": { "type": "string" }, "active": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query includeInactive: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerMarketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js", "services/marketplaceAssetContracts.js" ] } }, "/api/developer/products/{productId}/plugin-connections": { "get": { "summary": "Read private product connection events", "description": "Also ensures licensing rules. Rows use event_kind, status and plugin_version; event_type is not the connection-event field. Customer identity, device_hash and engagement_signal_id are null without customers.view; serial_id/serial_code are null without serials.view. Opaque failure_reason and metadata require both permissions, otherwise null/{}. Credential access alone does not grant private customer or serial data. Client filters cannot grant permissions.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/platform-tools" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, "developer_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": [ "integer", "null" ] }, "product_id": { "type": "integer", "minimum": 1 }, "serial_id": { "type": [ "integer", "null" ] }, "developer_customer_id": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "key_id": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "engagement_signal_id": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "event_kind": { "type": "string" }, "status": { "type": "string" }, "plugin_version": { "type": [ "string", "null" ] }, "environment": { "type": [ "string", "null" ] }, "device_hash": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "customer_email": { "type": [ "string", "null" ] }, "serial_code": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "credentials.view and assigned-product access.", "x-request-fields": [ "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaPlatformToolsService.js" ] } }, "/api/developer/products/{productId}/promo-codes": { "get": { "summary": "List product and workspace-wide promo codes", "description": "Includes product-specific and workspace-wide codes. Private customer eligibility and provider sync metadata are management information, not a public checkout response.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions-and-grants" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: promoCodes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "productId": { "type": [ "integer", "null" ] }, "code": { "type": "string" }, "purchaseType": { "enum": [ "one_time", "subscription" ] }, "discountType": { "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "minimumOrderCents": { "type": "integer" }, "minimumOrderAmount": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "redemptionCount": { "type": "integer" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "isActive": { "type": "boolean" }, "customerEligibilityMode": { "type": "string" }, "customerEligibility": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "customerEligibilityCount": { "type": "integer" }, "stripeTestCouponId": { "type": [ "string", "null" ] }, "stripeTestPromotionCodeId": { "type": [ "string", "null" ] }, "stripeLiveCouponId": { "type": [ "string", "null" ] }, "stripeLivePromotionCodeId": { "type": [ "string", "null" ] }, "stripeSyncError": { "type": [ "string", "null" ] }, "stripeSyncedAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view and assigned-product access; effective workspace product ownership.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaCommerceService.js", "services/promotionPurchaseTypeService.js" ] }, "post": { "summary": "Create a product promo code", "description": "New minimum spend is fixed at $9.99. Percent discounts cannot exceed 100. Amount discounts are dollar amounts, not cents. Omit purchaseType for one_time; a subscription code must match its product. global:true creates a workspace-wide code and requires all-products access; selected-product teammates receive 403 developer_team_all_products_scope_required before creation or Stripe sync. Stripe mirroring can have side effects; inspect stripeSyncError and environment-specific IDs, not just HTTP 201. A saved code does not bypass the $9.99 discounted paid-product floor.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions-and-grants" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: promoCode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "productId": { "type": [ "integer", "null" ] }, "code": { "type": "string" }, "purchaseType": { "enum": [ "one_time", "subscription" ] }, "discountType": { "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "minimumOrderCents": { "type": "integer" }, "minimumOrderAmount": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "redemptionCount": { "type": "integer" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "isActive": { "type": "boolean" }, "customerEligibilityMode": { "type": "string" }, "customerEligibility": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "customerEligibilityCount": { "type": "integer" }, "stripeTestCouponId": { "type": [ "string", "null" ] }, "stripeTestPromotionCodeId": { "type": [ "string", "null" ] }, "stripeLiveCouponId": { "type": [ "string", "null" ] }, "stripeLivePromotionCodeId": { "type": [ "string", "null" ] }, "stripeSyncError": { "type": [ "string", "null" ] }, "stripeSyncedAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.manage and assigned-product access; workspace-wide creation additionally requires all-products scope.", "x-request-fields": [ "maxRedemptions: integer,null", "startsAt: string,null", "expiresAt: string,null", "isActive: boolean", "allowDiscountOnSaleItems: boolean", "allowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "customerIds: array", "customerEmails: array", "code: string (required)", "discountType: percent | amount", "discountValue: number", "minimumOrderAmount: 9.99", "purchaseType: one_time | subscription", "global: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "PROMO_MINIMUM_FIXED", "PROMOTION_PRODUCT_TYPE_MISMATCH", "PROMO_CODE_EXISTS", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaCommerceService.js", "services/promotionPurchaseTypeService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1 }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "isActive": { "type": "boolean" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "allowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "customerIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "customerEmails": { "type": "array", "items": { "type": "string", "format": "email" } }, "code": { "type": "string" }, "discountType": { "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number", "minimum": 0 }, "minimumOrderAmount": { "const": 9.99 }, "purchaseType": { "enum": [ "one_time", "subscription" ] }, "global": { "type": "boolean" } }, "required": [ "code" ], "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/promo-codes/{promoCodeId}": { "put": { "summary": "Update limits, dates, eligibility and active state", "description": "Sparse update despite PUT: omitted fields retain their saved values. Does not change code, discount type or discount value. Minimum spend and purchase type are immutable. maxRedemptions:null clears the limit; a lower limit than completed plus reserved uses is rejected. Customer eligibility and Stripe sync can be updated. The saved productId determines scope: a workspace-wide code shown under a product still requires all-products access, even if the body supplies global:false or another productId. Selected-product writes fail with 403 developer_team_all_products_scope_required before update or Stripe sync.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions-and-grants" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "promoCodeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: promoCode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "productId": { "type": [ "integer", "null" ] }, "code": { "type": "string" }, "purchaseType": { "enum": [ "one_time", "subscription" ] }, "discountType": { "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "minimumOrderCents": { "type": "integer" }, "minimumOrderAmount": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "redemptionCount": { "type": "integer" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "isActive": { "type": "boolean" }, "customerEligibilityMode": { "type": "string" }, "customerEligibility": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "customerEligibilityCount": { "type": "integer" }, "stripeTestCouponId": { "type": [ "string", "null" ] }, "stripeTestPromotionCodeId": { "type": [ "string", "null" ] }, "stripeLiveCouponId": { "type": [ "string", "null" ] }, "stripeLivePromotionCodeId": { "type": [ "string", "null" ] }, "stripeSyncError": { "type": [ "string", "null" ] }, "stripeSyncedAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.manage and assigned-product access; editing an existing workspace-wide code additionally requires all-products scope.", "x-request-fields": [ "maxRedemptions: integer,null", "startsAt: string,null", "expiresAt: string,null", "isActive: boolean", "allowDiscountOnSaleItems: boolean", "allowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "customerIds: array", "customerEmails: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "PROMO_CODE_NOT_FOUND", "PROMO_MINIMUM_IMMUTABLE", "PROMOTION_TYPE_IMMUTABLE", "PROMOTION_LIMIT_BELOW_COMMITTED", "developer_team_all_products_scope_required" ], "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaCommerceService.js", "services/promotionPurchaseTypeService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1 }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "isActive": { "type": "boolean" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "allowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "customerIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "customerEmails": { "type": "array", "items": { "type": "string", "format": "email" } } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/promo-kit": { "get": { "summary": "Read product partner copy and media", "description": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: promo_kit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promo_kit": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] }, "put": { "summary": "Replace product partner copy and commercial presentation", "description": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product. Read the kit first. Omitted descriptive fields, lists and price suggestions reset to defaults/null; this is a replacement. Supported snake-case field names and msrp/suggested_sale_price decimal aliases are accepted. Saves suggestions and approved copy, not product pricing or an active sale.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: promo_kit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promo_kit": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product.", "x-request-fields": [ "title: string", "shortDescription: string", "longDescription: string", "featureBullets: array", "category: string", "tags: array", "msrp_cents: integer", "suggested_sale_price_cents: integer", "currency: string", "approvedDiscountRules: string", "systemRequirements: string", "licenseTerms: string", "emailCopy: string", "socialCopy: string", "adCopy: string", "brandGuidelines: string", "status: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "shortDescription": { "type": "string" }, "longDescription": { "type": "string" }, "featureBullets": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "msrp_cents": { "type": "integer" }, "suggested_sale_price_cents": { "type": "integer" }, "currency": { "type": "string" }, "approvedDiscountRules": { "type": "string" }, "systemRequirements": { "type": "string" }, "licenseTerms": { "type": "string" }, "emailCopy": { "type": "string" }, "socialCopy": { "type": "string" }, "adCopy": { "type": "string" }, "brandGuidelines": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/promo-kit/assets": { "post": { "summary": "Attach an authorized promotional media reference", "description": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product. Accepts asset_type/storage_key/mime_type/sort_order aliases. Requires a URL or storage key, not a binary file upload. Can initialize a missing promo kit.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product.", "x-request-fields": [ "assetType: image | logo | screenshot | audio_demo | video | document | banner | other", "title: string", "description: string", "url: string", "storageKey: string", "mimeType: string", "sortOrder: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assetType": { "type": "string", "enum": [ "image", "logo", "screenshot", "audio_demo", "video", "document", "banner", "other" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "storageKey": { "type": "string" }, "mimeType": { "type": "string" }, "sortOrder": { "type": "integer", "minimum": 0 } }, "additionalProperties": true, "anyOf": [ { "required": [ "url" ] }, { "required": [ "storageKey" ] }, { "required": [ "storage_key" ] } ] } } } } } }, "/api/developer/products/{productId}/promo-kit/assets/{assetId}": { "delete": { "summary": "Remove an owned promotional asset reference", "description": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product. Deletes the reference row; does not promise deletion of the underlying stored file or erase customer purchases.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: deleted, asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "asset": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ] }, "patch": { "summary": "Edit a product promotional asset reference", "description": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product. Omitted asset fields retain saved values; the URL or storage key must still resolve in the normalized reference. Does not change marketplace artwork approval.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-management" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "partners.manage and assigned-product access, including GET. The product must belong to the effective developer; all-products scope is not required for an assigned product.", "x-request-fields": [ "assetType: image | logo | screenshot | audio_demo | video | document | banner | other", "title: string", "description: string", "url: string", "storageKey: string", "mimeType: string", "sortOrder: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPartnerHubRoutes.js", "controllers/partnerHubController.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "assetType": { "type": "string", "enum": [ "image", "logo", "screenshot", "audio_demo", "video", "document", "banner", "other" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "storageKey": { "type": "string" }, "mimeType": { "type": "string" }, "sortOrder": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/readiness": { "get": { "summary": "Inspect one product readiness", "description": "Diagnostic output, not publication or checkout activation. Read blockers, warnings, categories, evidence and action links; a percentage alone is not approval. Developer checks include billing, settlement and email configuration and can initialize/read settlement or sender state. Do not use these as a zero-write uptime probe, a provider-verification certificate or a promise of live native-host runtime verification.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/readiness" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: scope, status, goLiveReady, completionPercent, developer_id, product_id, storefront_id, generated_at, blockers, warnings, categories, blockingCount, warningCount, requiredIncompleteCount, nextAction, nextActionCode, nextActionCategory, launchChecklist, categorySummary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "enum": [ "developer", "product", "storefront" ] }, "status": { "type": "string" }, "goLiveReady": { "type": "boolean" }, "completionPercent": { "type": "number" }, "developer_id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "storefront_id": { "type": [ "integer", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "weight": { "type": "number" }, "completionPercent": { "type": "number" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "href": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "blockingCount": { "type": "integer" }, "warningCount": { "type": "integer" }, "requiredIncompleteCount": { "type": "integer" }, "nextAction": { "type": [ "string", "null" ] }, "nextActionCode": { "type": [ "string", "null" ] }, "nextActionCategory": { "type": [ "string", "null" ] }, "launchChecklist": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "categorySummary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Actual product owner or platform admin; a selected-product team assignment is not sufficient.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerReadinessRoutes.js", "services/developerReadinessService.js", "services/developerReadinessSummaryService.js" ] } }, "/api/developer/products/{productId}/relationships": { "get": { "summary": "Read active or inactive product relationships", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/expansions" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: relationships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "parentProductId": { "type": [ "integer", "null" ] }, "childProductId": { "type": "integer", "minimum": 1 }, "relationshipType": { "type": "string", "enum": [ "expansion_requires_parent", "expansion_standalone" ] }, "status": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owner/admin product-management surface. Both parent and child must belong to the same developer. Do not assume these compatibility handlers support every delegated team role.", "x-request-fields": [ "query status: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerExpansionRoutes.js", "services/expansionFoundationService.js" ] } }, "/api/developer/products/{productId}/rent-to-own": { "get": { "summary": "Read product override", "description": "Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "billingInterval": { "type": "string" }, "installmentCount": { "type": "integer" }, "priceStrategy": { "type": "string" }, "premiumBps": { "type": "integer" }, "fixedTotalCents": { "type": "integer", "minimum": 0 }, "fixedInstallmentCents": { "type": "integer", "minimum": 0 }, "promotionPolicy": { "type": "string" }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ] }, "put": { "summary": "Update product override", "description": "Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "billingInterval": { "type": "string" }, "installmentCount": { "type": "integer" }, "priceStrategy": { "type": "string" }, "premiumBps": { "type": "integer" }, "fixedTotalCents": { "type": "integer", "minimum": 0 }, "fixedInstallmentCents": { "type": "integer", "minimum": 0 }, "promotionPolicy": { "type": "string" }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "enabled: boolean", "billingInterval: string", "installmentCount: integer", "priceStrategy: string", "premiumBps: integer", "fixedTotalCents: integer", "fixedInstallmentCents: integer", "promotionPolicy: string", "failedPaymentGraceDays: integer", "cancellationBehavior: string", "displayTitle: string", "displayDisclaimer: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "billingInterval": { "type": "string" }, "installmentCount": { "type": "integer" }, "priceStrategy": { "type": "string" }, "premiumBps": { "type": "integer" }, "fixedTotalCents": { "type": "integer", "minimum": 0 }, "fixedInstallmentCents": { "type": "integer", "minimum": 0 }, "promotionPolicy": { "type": "string" }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/rent-to-own/preview": { "post": { "summary": "Preview the configured option", "description": "Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: option, productSettings, effectiveSettings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "option": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "eligible": { "type": "boolean" }, "enabled": { "type": "boolean" }, "ineligibilityReasons": { "type": "array", "items": { "type": "string" } }, "currency": { "type": "string" }, "cashPriceCents": { "type": "integer", "minimum": 0 }, "installmentAmountCents": { "type": "integer", "minimum": 0 }, "installmentCount": { "type": "integer" }, "totalContractCents": { "type": "integer", "minimum": 0 }, "roundingAdjustmentCents": { "type": "integer" }, "billingInterval": { "type": "string" }, "priceStrategy": { "type": "string" }, "promotionPolicy": { "type": "string" }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "termsUrl": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "productionExposureAllowed": { "type": "boolean" } }, "additionalProperties": true }, "productSettings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "billingInterval": { "type": "string" }, "installmentCount": { "type": "integer" }, "priceStrategy": { "type": "string" }, "premiumBps": { "type": "integer" }, "fixedTotalCents": { "type": "integer", "minimum": 0 }, "fixedInstallmentCents": { "type": "integer", "minimum": 0 }, "promotionPolicy": { "type": "string" }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "effectiveSettings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "defaultBillingInterval": { "type": "string" }, "defaultInstallmentCount": { "type": "integer" }, "minInstallmentCount": { "type": "integer" }, "maxInstallmentCount": { "type": "integer" }, "defaultPriceStrategy": { "type": "string" }, "defaultPremiumBps": { "type": "integer" }, "minCashPriceCents": { "type": "integer", "minimum": 0 }, "maxCashPriceCents": { "type": "integer", "minimum": 0 }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "promotionPolicy": { "type": "string" }, "allowEarlyPayoff": { "type": "boolean" }, "customerTermsUrl": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ] } }, "/api/developer/products/{productId}/requirements": { "get": { "summary": "Read parent-product access requirements", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/expansions" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product, relationships, required_parent_product_ids.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "productType": { "type": "string" }, "isExpansion": { "type": "boolean" }, "parentProductId": { "type": [ "integer", "null" ] }, "requiredParentProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "requiresParentEntitlement": { "type": "boolean" }, "grantsParentAccess": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "hidden" ] }, "expansionSortOrder": { "type": "integer" }, "expansionAccessState": { "type": "string" }, "expansionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "ownerUserId": { "type": "integer", "minimum": 1 }, "marketplaceVisible": { "type": "boolean" }, "isDraft": { "type": "boolean" } }, "additionalProperties": true }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "parentProductId": { "type": [ "integer", "null" ] }, "childProductId": { "type": "integer", "minimum": 1 }, "relationshipType": { "type": "string", "enum": [ "expansion_requires_parent", "expansion_standalone" ] }, "status": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "required_parent_product_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owner/admin product-management surface. Both parent and child must belong to the same developer. Do not assume these compatibility handlers support every delegated team role.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerExpansionRoutes.js", "services/expansionFoundationService.js" ] } }, "/api/developer/products/{productId}/rest-config": { "get": { "summary": "Read private product integration configuration", "description": "Can ensure package credentials. productKey and productKeyPreview are masked previews; secretReturned is false. Do not use this response as a full credential or health-monitoring guarantee.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-dashboard" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: restApi.", "content": { "application/json": { "schema": { "type": "object", "properties": { "restApi": { "type": "object", "properties": { "status": { "type": "string" }, "apiBaseUrl": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": [ "string", "null" ] }, "productKey": { "type": [ "string", "null" ] }, "productKeyPreview": { "type": [ "string", "null" ] }, "environment": { "type": "string" }, "apiStatus": { "type": "string" }, "lastRequestAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretReturned": { "const": false } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "credentials.view and assigned-product access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerProductDashboardRoutes.js", "controllers/developerProductDashboardController.js", "services/productDashboardService.js" ] } }, "/api/developer/products/{productId}/reviews": { "get": { "summary": "Read private reviews for one assigned product", "description": "Default limit 50, maximum 100. Private response can include hidden/pending reviews, customer email and moderation metadata; never publish it as the storefront review feed. Page is clamped to available pages.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/review-imports" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "rating", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: reviews, pagination, counts, summary, filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "productId": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "customerEmail": { "type": [ "string", "null" ] }, "customerId": { "type": [ "integer", "null" ] }, "imported": { "type": "boolean" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "additionalProperties": true }, "counts": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "filters": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "reviews.view and assigned-product scope. Route productId overrides query productId.", "x-request-fields": [ "query page: string", "query limit: string", "query search: string", "query status: string", "query rating: string", "query dateRange: string", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerReviewRoutes.js", "services/productReviewService.js" ] } }, "/api/developer/products/{productId}/subscription-settings": { "get": { "summary": "Return beta product subscription settings for a developer-owned product.", "description": "Side effects: Ensures a product_subscription_settings row exists for the product.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscriptions" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "settings { enabled, billingInterval, trialDays, failedPaymentGraceDays, cancellationBehavior }, betaEnabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer", "enum": [ 0, 7, 14, 30 ] }, "failedPaymentGraceDays": { "type": "integer", "enum": [ 0, 3, 7, 14 ] }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] } }, "additionalProperties": true }, "betaEnabled": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product settings.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaCommerceService.js" ] }, "put": { "summary": "Update product subscription settings.", "description": "This is a mutation and is not used during read-only screenshot capture. These are supported settings inputs, not authority to override the managed fourteen_days_v1 recovery policy. Review the subscription recovery guide for effective deadlines. Changing monthly/yearly cadence with active, trialing, past_due or unpaid standalone or linked bundle contracts returns 409 SUBSCRIPTION_BILLING_INTERVAL_LOCKED. Keep existing contracts on their cadence and create a separate offer for the new interval. This is a settings replacement, not a sparse PATCH: omitted enabled defaults false, billingInterval monthly, trialDays 0, failedPaymentGraceDays 14 and cancellationBehavior access_until_period_end. Read current settings and send the intended complete values. Legacy lock_immediately can be stored, but managed customer cancellation remains effective at paid-period end; legacy grace input does not replace fourteen_days_v1 recovery. Side effects: Writes subscription settings and records product setup activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscriptions" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated settings and betaEnabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer", "enum": [ 0, 7, 14, 30 ] }, "failedPaymentGraceDays": { "type": "integer", "enum": [ 0, 3, 7, 14 ] }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] } }, "additionalProperties": true }, "betaEnabled": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product settings.", "x-request-fields": [ "enabled: boolean", "billingInterval: monthly | yearly", "trialDays: 0 | 7 | 14 | 30", "failedPaymentGraceDays: 0 | 3 | 7 | 14", "cancellationBehavior: access_until_period_end | lock_immediately" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "SUBSCRIPTION_BILLING_INTERVAL_LOCKED" ], "x-source-files": [ "routes/developerPlatformToolsRoutes.js", "services/betaCommerceService.js", "services/subscriptionPlanSafetyService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer", "enum": [ 0, 7, 14, 30 ] }, "failedPaymentGraceDays": { "type": "integer", "enum": [ 0, 3, 7, 14 ] }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] } }, "additionalProperties": true } } } } } }, "/api/developer/products/{productId}/versions": { "get": { "summary": "Read current product version metadata", "description": "Reads saved product_file_versions when available; otherwise derives the compatible current version from product features. Separate from versioned delivery asset management.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/product-dashboard" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "version": { "type": "string" }, "changelog": { "type": "string" }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time" }, "isCurrent": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "products.view and assigned-product access.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerProductDashboardRoutes.js", "controllers/developerProductDashboardController.js", "services/productDashboardService.js" ] } }, "/api/developer/products/catalog": { "get": { "summary": "Search the private developer product catalog", "description": "Requires products.view and returns only permitted products. This is a private dashboard catalog, not the public marketplace. Default status all excludes archived products; request archived explicitly. Page is clamped to available pages. The summary covers permitted catalog products, not only the filtered page. monthlySalesAvailable:false and null totals mean reporting is unavailable, not zero sales. hisePackageEligible is a compatibility field for activation capability, not a statement that a product uses HISE.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "enum": [ "all", "published", "draft", "hidden", "archived", "needs_review" ] }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "licensing", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "enum": [ "updated", "name_az", "name_za", "newest", "oldest", "sales", "downloads" ] }, "required": false, "description": "" }, { "name": "view", "in": "query", "schema": { "enum": [ "table", "grid" ] }, "required": false, "description": "" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 5, "maximum": 50, "default": 10 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: summary, products, pagination, filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "totalProducts": { "type": "integer" }, "archived": { "type": "integer" }, "published": { "type": "integer" }, "drafts": { "type": "integer" }, "hidden": { "type": "integer" }, "needsAttention": { "type": "integer" }, "monthlySalesAvailable": { "type": "boolean" }, "monthlySalesCents": { "type": [ "number", "null" ] }, "monthlySales": { "type": [ "number", "null" ] }, "monthlySalesDeltaPercent": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "environment": { "type": "string" } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "sku": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "typeLabel": { "type": "string" }, "category": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "status": { "type": "string" }, "storefrontStatus": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "salePrice": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "licensingType": { "type": "string" }, "downloads": { "type": [ "number", "null" ] }, "sales": { "type": "number" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "needsAttention": { "type": "boolean" }, "attentionReasons": { "type": "array", "items": { "type": "string" } }, "hisePackageEligible": { "type": "boolean" } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "additionalProperties": true }, "filters": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } }, "types": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": true } }, "statuses": { "type": "array", "items": { "type": "string" } }, "licensingTypes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "query search: string", "query q: string", "query status: value", "query type: string", "query category: string", "query licensing: string", "query sort: value", "query view: value", "query page: integer", "query limit: integer", "query currency: string", "query environment: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerProductCatalogRoutes.js", "controllers/developerProductCatalogController.js", "services/productCatalogService.js", "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] } }, "/api/developer/promotions": { "get": { "summary": "List promotion overview: promo codes, scheduled deals, offers, and stats.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [ { "name": "promoLimit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "dealLimit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offerLimit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "promoCodes[], deals[], offers[], stats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "imports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "stats": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query promoLimit: integer", "query dealLimit: integer", "query offerLimit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] }, "post": { "summary": "Create a promo code, scheduled deal, or promotion offer based on type/offerType.", "description": "type selects promo_code, subscription_promo_code or scheduled_deal; other supported offerType values use the offer path. Per-type validation, scope, stacking and paid-price rules still apply. Side effects: Writes promo_codes, product_scheduled_deals, or developer_promotion_offers depending on input.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "201": { "description": "201 created promo code, deal, or offer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "offer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checkoutBacked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null", "endsAt: string,null", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/activity": { "get": { "summary": "Read recent promotion summaries", "description": "Requires marketing.view and assigned-product scope. Returns up to 50 creation/status summaries synthesized from the limited current promo/deal/offer lists, not an immutable audit log or complete event history.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: activity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "activity": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] } }, "/api/developer/promotions/bundles": { "get": { "summary": "List bundle-like promotion offers.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "200": { "description": "offers[] filtered to bundle offer types.", "content": { "application/json": { "schema": { "type": "object", "properties": { "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "stats": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] }, "post": { "summary": "Create bundle-like promotion offer.", "description": "Side effects: Changes or processes the authorized resource: Create bundle-like promotion offer.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "201": { "description": "201 offer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "offer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checkoutBacked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null", "endsAt: string,null", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/deals": { "post": { "summary": "Create a scheduled deal through the compatible route", "description": "Compatibility alias of scheduled-deals creation. Requires marketing.view and marketing.manage plus permitted product scope. Paid-price, scheduling and conflict validation apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: promoCode, deal, offer, checkoutBacked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "offer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checkoutBacked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer (required)", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null (required)", "endsAt: string,null (required)", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number (required)", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "required": [ "productId", "salePrice", "startsAt", "endsAt" ] } } } } } }, "/api/developer/promotions/deals/{dealId}/campaign-draft": { "post": { "summary": "Create a campaign draft from a deal", "description": "Requires marketing.view and marketing.manage and access to the scheduled deal product. Creates a new campaign draft and links it to the deal; it does not send, schedule or approve email. Repeat calls can create additional drafts. Product publication warnings and campaign audience/suppression checks remain relevant.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [ { "name": "dealId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: campaign, audience, deal, product, warnings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "type": "string" }, "audienceEstimateCount": { "type": "integer" }, "audienceSnapshotCount": { "type": "integer" }, "testSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sendStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureReason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "report": { "type": "object", "properties": { "recipients": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "sent": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "uniqueOpened": { "type": "integer" }, "uniqueClicked": { "type": "integer" }, "delivered": { "type": [ "integer", "null" ] }, "recordedDelivered": { "type": "integer" }, "deliverySource": { "type": "string", "enum": [ "not_sent", "provider_channel", "recorded_receipts", "unavailable" ] }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "recordedOpenEvents": { "type": "integer" }, "recordedClickEvents": { "type": "integer" }, "engagementUnchecked": { "type": "integer" }, "engagementDenominator": { "type": "integer" }, "providerBounced": { "type": [ "integer", "null" ] }, "providerUnsubscribed": { "type": [ "integer", "null" ] }, "providerComplaints": { "type": [ "integer", "null" ] }, "performanceSource": { "type": "string", "enum": [ "elastic_channel", "recorded_events" ] }, "providerStatsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "providerStatsError": { "type": [ "string", "null" ] }, "providerStatsStatus": { "type": "string", "enum": [ "not_sent", "pending", "retrying", "ready", "stale", "unavailable" ] }, "attributedOrders": { "type": "integer" }, "revenueCents": { "type": "integer" }, "openRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickRate": { "type": "object", "properties": { "percent": { "type": [ "number", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "clickToOpenRate": { "type": "number" }, "statusBreakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "progress": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "completed": { "type": "integer" }, "remaining": { "type": "integer" }, "percentComplete": { "type": "number" } }, "additionalProperties": true }, "denominatorSource": { "type": "string", "enum": [ "sent", "delivered" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "audience": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "resolvedFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "totalMatchingContacts": { "type": "integer" }, "finalSendableEstimate": { "type": "integer" }, "selectedProductOwnerCount": { "type": [ "integer", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "object", "properties": { "noMarketingConsent": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "suppressed": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "invalid": { "type": "integer" }, "missingEmail": { "type": "integer" }, "duplicateEmail": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "imageUrl": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": true }, "warnings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.", "x-request-fields": [ "name: string", "subject: string", "preheader: string", "bodyHtml: string", "bodyText: string", "audienceFilter: object", "fromName: string", "fromEmail: string", "replyToEmail: string", "primaryProductId: integer", "heroImageUrl: string", "ctaLabel: string", "ctaUrl: string", "sourceType: string", "sourceId: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js", "services/marketingCampaignService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "subject": { "type": "string" }, "preheader": { "type": "string" }, "bodyHtml": { "type": "string" }, "bodyText": { "type": "string" }, "audienceFilter": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all_active", "owns_products", "does_not_own_products", "purchased_between", "imported", "saved_segment" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "purchasedFrom": { "type": "string" }, "purchasedTo": { "type": "string" }, "segmentId": { "type": "integer", "minimum": 1 }, "noOpenDays": { "type": "integer" }, "noClickDays": { "type": "integer" }, "openedDays": { "type": "integer" }, "clickedDays": { "type": "integer" }, "sentDays": { "type": "integer" }, "minSentCount": { "type": "integer" }, "source": { "type": "string" }, "lastActivityFrom": { "type": "string" }, "lastActivityTo": { "type": "string" } }, "additionalProperties": true }, "fromName": { "type": "string" }, "fromEmail": { "type": "string", "format": "email" }, "replyToEmail": { "type": "string", "format": "email" }, "primaryProductId": { "type": "integer", "minimum": 1 }, "heroImageUrl": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaUrl": { "type": "string" }, "sourceType": { "type": "string" }, "sourceId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/deals/{dealId}/cancel": { "post": { "summary": "Cancel a scheduled deal.", "description": "Side effects: Cancels product scheduled deal.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [ { "name": "dealId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Canceled deal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] } }, "/api/developer/promotions/group-buys": { "get": { "summary": "List group-buy configuration records", "description": "Compatibility filtered list of community_group_buy offers. Requires marketing.view and assigned-product scope. A saved offer or target counter is not proof of complete group-buy collection/fulfillment. Prefer the promotion workspace and inspect checkoutBacked.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: offers, stats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "stats": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] }, "post": { "summary": "Create group-buy configuration", "description": "Requires marketing.view and marketing.manage plus owned/assigned products. Forces community_group_buy offerType. This is offer configuration, not a promise of automatic group-buy charging or complete group-buy lifecycle support; inspect checkoutBacked and supported checkout behavior.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: promoCode, deal, offer, checkoutBacked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "offer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checkoutBacked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null", "endsAt: string,null", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/offers": { "post": { "summary": "Create a supported multi-product, tiered-cart, bundle, BOGO or group-buy offer.", "description": "multi_product_discount and tiered_cart_discount support activation:automatic or code. Tiered offers require selected one-time productIds and 1-50 unique quantityTiers with positive integer quantity no greater than the selected product count, and discountPercent greater than 0 and at most 100. Quantities count distinct positive-priced eligible products, not cart units. The highest reached quantity threshold applies to all eligible copies. Code activation requires code; automatic offers do not require one. Checkout applies the single best qualifying automatic offer, promo stacking rules and the $9.99 paid minimum. Other offer families retain their own eligibility; a saved record is not proof every legacy type is checkout-backed. Side effects: Writes the offer; some supported offer types also create a backing promo code.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "201": { "description": "201 offer; inspect checkoutBacked. Cart discounts are unlimited by default; optional usage limits work with automatic or code activation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "offer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checkoutBacked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null", "endsAt: string,null", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/offers/{offerId}": { "patch": { "summary": "Edit an offer under workspace guards", "description": "Requires marketing.view and marketing.manage plus the complete offer product scope. Uses the workspace offer edit path; immutable product/discount fields and archived-state guards still apply. checkoutBacked is not guaranteed true for every offer type.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [ { "name": "offerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: offer, checkoutBacked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "offer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checkoutBacked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null", "endsAt: string,null", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/overview": { "get": { "summary": "Read the compatible promotion summary", "description": "Compatibility alias of GET /api/developer/promotions. Uses marketing.view and assigned-product filtering. These limited-list summary statistics are not a complete accounting statement.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [ { "name": "promoLimit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "dealLimit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offerLimit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: promoCodes, deals, offers, imports, stats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "imports": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "stats": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.", "x-request-fields": [ "query promoLimit: integer", "query dealLimit: integer", "query offerLimit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] } }, "/api/developer/promotions/promo-codes": { "get": { "summary": "List promo codes with stats.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "200": { "description": "promoCodes[], stats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "stats": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] }, "post": { "summary": "Create product-scoped or storewide promo code.", "description": "Omitting productId selects the storewide path, which requires all-products scope. Side effects: Creates promo code and may use first developer product for storewide backing.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "201": { "description": "201 promoCode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "offer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checkoutBacked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string (required)", "productId: integer", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount (required)", "discountValue: number (required)", "startsAt: string,null", "endsAt: string,null", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "required": [ "code", "discountType", "discountValue" ] } } } } } }, "/api/developer/promotions/promo-codes/{promoCodeId}": { "patch": { "summary": "Update a developer-owned promo code.", "description": "Side effects: Updates promo code through product promo-code service.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [ { "name": "promoCodeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated promoCode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "offer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checkoutBacked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null", "endsAt: string,null", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/promo-codes/import": { "post": { "summary": "Apply a permitted coupon import", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: import, summary, rows, preview, warnings, errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "import": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "summary": { "type": "object", "properties": { "imported": { "type": "integer" }, "skipped": { "type": "integer" }, "invalid": { "type": "integer" } }, "additionalProperties": true }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "preview": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "warnings": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "csv: string", "csvText: string", "defaults: object", "customerMode: ignore | email_specific", "useDefaultForZeroDiscount: boolean", "sourceFilename: string", "diagnostics: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string" }, "csvText": { "type": "string" }, "defaults": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "customerMode": { "type": "string", "enum": [ "ignore", "email_specific" ] }, "useDefaultForZeroDiscount": { "type": "boolean" }, "sourceFilename": { "type": "string" }, "diagnostics": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/promo-codes/import/preview": { "post": { "summary": "Validate an import before applying it", "description": "CSV is a JSON string, not a multipart upload. Inspect every warning and duplicate before import.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: import, summary, rows, preview, warnings, errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "import": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "summary": { "type": "object", "properties": { "imported": { "type": "integer" }, "skipped": { "type": "integer" }, "invalid": { "type": "integer" } }, "additionalProperties": true }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "preview": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "warnings": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "csv: string", "csvText: string", "defaults: object", "customerMode: ignore | email_specific", "useDefaultForZeroDiscount: boolean", "sourceFilename: string", "diagnostics: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string" }, "csvText": { "type": "string" }, "defaults": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "customerMode": { "type": "string", "enum": [ "ignore", "email_specific" ] }, "useDefaultForZeroDiscount": { "type": "boolean" }, "sourceFilename": { "type": "string" }, "diagnostics": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/promo-codes/imports": { "get": { "summary": "Read scoped import history", "description": "Requires marketing.view. Only import jobs whose complete row scope is visible to the caller are returned; selected-product access cannot reveal mixed/foreign jobs. Read the import detail separately for row errors.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "required": false, "description": "" }, { "name": "importLimit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: imports.", "content": { "application/json": { "schema": { "type": "object", "properties": { "imports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "actorUserId": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "sourceFilename": { "type": [ "string", "null" ] }, "totalRows": { "type": "integer" }, "validRows": { "type": "integer" }, "importedRows": { "type": "integer" }, "skippedRows": { "type": "integer" }, "errorRows": { "type": "integer" }, "duplicateRows": { "type": "integer" }, "options": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "marketing.view; writes additionally require marketing.manage. Effective workspace and complete product-scope checks apply.", "x-request-fields": [ "query limit: integer", "query importLimit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] } }, "/api/developer/promotions/promo-codes/imports/{importJobId}": { "get": { "summary": "Inspect import results", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "importJobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: import, summary, rows, preview, warnings, errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "import": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "summary": { "type": "object", "properties": { "imported": { "type": "integer" }, "skipped": { "type": "integer" }, "invalid": { "type": "integer" } }, "additionalProperties": true }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "preview": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "warnings": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] } }, "/api/developer/promotions/scheduled-deals": { "get": { "summary": "List scheduled product deals.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "200": { "description": "deals[], stats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "stats": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] }, "post": { "summary": "Create scheduled product deal.", "description": "Side effects: Writes product_scheduled_deals.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/promotions" }, "parameters": [], "responses": { "201": { "description": "201 deal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "promoCode": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "offer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checkoutBacked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer (required)", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null (required)", "endsAt: string,null (required)", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "required": [ "productId", "startsAt", "endsAt" ] } } } } } }, "/api/developer/promotions/workspace": { "get": { "summary": "List workspace entries and filters", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "kind", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: items, summary, pagination, canManage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pages": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": true }, "canManage": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query kind: string", "query status: string", "query type: string", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] } }, "/api/developer/promotions/workspace/{kind}": { "post": { "summary": "Create a supported kind", "description": "kind is code or offer. offerType:tiered_cart_discount accepts productIds, activation:automatic|code and quantityTiers:[{quantity,discountPercent}]. Thresholds count distinct eligible positive-priced one-time products, not units; the highest reached threshold applies to every eligible copy. Use POST /offers for the same per-type eligibility details. New reward coupons use the fixed $9.99 minimum spend.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null", "endsAt: string,null", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/workspace/{kind}/{id}": { "get": { "summary": "Read an entry", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] }, "patch": { "summary": "Update the entry", "description": "Code, products and discount can be immutable after creation; duplicate the promotion for a different immutable configuration. Archived records must be restored before editing.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "type: string", "offerType: string", "title: string", "name: string", "code: string", "productId: integer", "productIds: array", "subscriptionProductIds: array", "activation: automatic | code", "quantityTiers: array. Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "purchaseType: one_time | subscription", "discountType: percent | amount", "discountValue: number", "startsAt: string,null", "endsAt: string,null", "expiresAt: string,null", "maxRedemptions: integer,null. Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses.", "minimumOrderAmount: number", "salePrice: number", "allowDiscountOnSaleItems: boolean", "isActive: boolean", "status: string", "requiredQuantity: integer", "rewardQuantity: integer", "groupTarget: integer", "rewardMinimumOrderAmount: number", "rewardMaxRedemptions: integer", "rewardExpiresInDays: integer", "rewardCodePrefix: string", "rewardGrantScope: string", "rewardIncludeFreeItems: boolean", "rewardRefundPolicy: string", "rewardAllowAutomaticOfferStacking: boolean", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2147483647, "description": "Optional total redemption cap. Omitted on creation or null means unlimited; null clears an existing cap. Omitted on update preserves the cap. Single and tiered cart offers support this for automatic and code activation. A finite cap cannot be below completed plus reserved uses." }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": "integer" }, "rewardQuantity": { "type": "integer" }, "groupTarget": { "type": "integer" }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/promotions/workspace/{kind}/{id}/{action}": { "post": { "summary": "Run a supported archive/restore or reconciliation action", "description": "action is archive, restore, reconcile-reservations or retry-rewards. Archive/restore return the item; reservation recovery returns checked/released/pending/needsReview; reward recovery returns processed/completed/failed/skipped. Reward retry only applies to purchase-reward offers; these recovery operations are not dry runs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: item, checked, released, pending, needsReview, processed, completed, failed, skipped.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "offerType": { "type": "string" }, "title": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "activation": { "type": "string", "enum": [ "automatic", "code" ] }, "quantityTiers": { "type": "array", "minItems": 1, "maxItems": 50, "description": "Unique positive product-count thresholds, each reachable by the selected eligible product set. Sorted by quantity on save.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "discountPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "quantity", "discountPercent" ], "additionalProperties": true } }, "purchaseType": { "type": "string", "enum": [ "one_time", "subscription" ] }, "discountType": { "type": "string", "enum": [ "percent", "amount" ] }, "discountValue": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "maxRedemptions": { "type": [ "integer", "null" ] }, "minimumOrderAmount": { "type": "number" }, "salePrice": { "type": "number" }, "allowDiscountOnSaleItems": { "type": "boolean" }, "isActive": { "type": "boolean" }, "status": { "type": "string" }, "requiredQuantity": { "type": [ "integer", "null" ] }, "rewardQuantity": { "type": [ "integer", "null" ] }, "groupTarget": { "type": [ "integer", "null" ] }, "rewardMinimumOrderAmount": { "type": "number" }, "rewardMaxRedemptions": { "type": "integer" }, "rewardExpiresInDays": { "type": "integer" }, "rewardCodePrefix": { "type": "string" }, "rewardGrantScope": { "type": "string" }, "rewardIncludeFreeItems": { "type": "boolean" }, "rewardRefundPolicy": { "type": "string" }, "rewardAllowAutomaticOfferStacking": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "kind": { "type": "string" }, "productNames": { "type": "array", "items": { "type": "string" } }, "checkoutBacked": { "type": "boolean" }, "promoCodeId": { "type": [ "integer", "null" ] }, "savedStatus": { "type": "string" }, "revenue": { "type": [ "number", "null" ] }, "purchases": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "checked": { "type": "integer" }, "released": { "type": "integer" }, "pending": { "type": "integer" }, "needsReview": { "type": "integer" }, "processed": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "skipped": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js", "services/promotionReservationService.js", "services/promotionRewardRecoveryService.js" ] } }, "/api/developer/promotions/workspace/{kind}/{id}/performance": { "get": { "summary": "Read activity/performance", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: purchases, revenue, rewards.", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchases": { "type": "integer" }, "revenue": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "amountCents": { "type": "integer" } }, "additionalProperties": true } }, "rewards": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerPromotionRoutes.js", "services/developerPromotionService.js", "services/promotionWorkspaceService.js" ] } }, "/api/developer/purchases": { "get": { "summary": "Search grouped purchase and access history", "description": "Account permissions and assigned products determine scope; query filters cannot expand it. Purchase rows group items by purchase_key. Access-only rows have order_type:access_grant, financial_record:false, invoice_available:false and null order_id/order_item_id. display_order_id falls back to ACCESS-; an earned subscription product can instead display the funding order, with original_subscription_order_id as a separate reference and zero-cost item totals. Neither display value makes the access row a payment, invoice or refundable order. channel:subscription includes subscription history; recordType:access selects access-only rows. canRefund is a caller capability, not per-row eligibility. Purchase identifiers can also include external/manual references; use the refund preview for an eligible managed-payment order.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "channel", "in": "query", "schema": { "enum": [ "all", "direct", "marketplace", "reseller", "manual", "import", "free", "subscription", "other" ] }, "required": false, "description": "" }, { "name": "productIds", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "resellerId", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "provider", "in": "query", "schema": { "enum": [ "all", "stripe", "paypal", "other", "unknown" ] }, "required": false, "description": "" }, { "name": "refundStatus", "in": "query", "schema": { "enum": [ "all", "none", "partial", "full", "unknown" ] }, "required": false, "description": "" }, { "name": "recordType", "in": "query", "schema": { "enum": [ "all", "order", "pool", "access" ] }, "required": false, "description": "" }, { "name": "dateFrom", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateTo", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: rows, total, page, pageSize, canRefund.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "order_item_id": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "invoice_available": { "type": "boolean" }, "financial_record": { "type": "boolean" }, "order_type": { "type": "string" }, "purchase_channel": { "type": "string" }, "access_entitlement_id": { "type": [ "integer", "string" ], "minLength": 1 }, "entitlement_id": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "entitlement_state": { "type": [ "string", "null" ] }, "display_order_id": { "type": "string" }, "original_subscription_order_id": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "currency": { "type": "string" }, "item_subtotal_cents": { "type": "integer" }, "final_total_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "purchase_key": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "items": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "order_item_id": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "invoice_available": { "type": "boolean" }, "financial_record": { "type": "boolean" }, "order_type": { "type": "string" }, "purchase_channel": { "type": "string" }, "access_entitlement_id": { "type": [ "integer", "string" ], "minLength": 1 }, "entitlement_id": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "entitlement_state": { "type": [ "string", "null" ] }, "display_order_id": { "type": "string" }, "original_subscription_order_id": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "currency": { "type": "string" }, "item_subtotal_cents": { "type": "integer" }, "final_total_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "purchase_key": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "canRefund": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query dateRange: string", "query productId: integer", "query channel: value", "query productIds: string", "query resellerId: string", "query provider: value", "query refundStatus: value", "query recordType: value", "query dateFrom: string", "query dateTo: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/purchases/{orderId}/invoice.pdf": { "get": { "summary": "Read an authorized invoice", "description": "Returns a private invoice attachment. INVOICE_PAGINATION_REQUIRED is an error rather than a truncated invoice.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: application/pdf.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js", "services/customerInformationUpdateService.js" ] } }, "/api/developer/purchases/{orderId}/refund": { "get": { "summary": "Preview eligibility and the original refund breakdown.", "description": "Developer JWT, refunds.create permission, and scope over every affected product are required. No payment is initiated. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/refunds" }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemIds", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Eligible preview with snapshot, availableItems, deadline, confirmationToken, and any unavailableReason; an existing blocking operation can return eligible:false.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "unavailableReason": { "type": [ "string", "null" ] }, "confirmationToken": { "type": "string" }, "deadline": { "type": "string" }, "snapshot": { "type": "object", "properties": {}, "additionalProperties": true }, "availableItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } }, "itemSelectionUnavailableReason": { "type": [ "string", "null" ] }, "operation": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owned purchase and every affected product; refunds.create is required for preview and confirmation.", "x-request-fields": [ "query itemIds: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerRefundService.js" ] }, "post": { "summary": "Confirm the current preview and request the refund.", "description": "Do not send amount, amountCents, or items. Custom amount requests are rejected. The original capture must be eligible and the selected items must remain unrefunded. Side effects: Confirm the current preview and request the refund. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/refunds" }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "202 with operation. Track its state; acceptance is not provider completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Owned purchase and every affected product; refunds.create is required for preview and confirmation.", "x-request-fields": [ "confirm: true (required)", "confirmationToken: string (required)", "reason: string (required)", "itemIds: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerRefundService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "const": true }, "confirmationToken": { "type": "string" }, "reason": { "type": "string", "minLength": 3, "maxLength": 1000 }, "itemIds": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1 } } }, "required": [ "confirm", "confirmationToken", "reason" ], "additionalProperties": false } } } } } }, "/api/developer/purchases/{orderItemId}/remove-access": { "post": { "summary": "Remove selected access under the supported policy", "description": "Removes the selected purchase access and optionally hides its record. This does not issue a provider refund. For a manual history row with metadata.manualGrantExistingAccess:true, removal without deleteRecord:true returns 409 MANUAL_GRANT_HISTORY_ONLY. deleteRecord:true hides that history only and returns recordOnly:true with zero revocations; manage the original entitlement or serial separately. Access-only ACCESS references are not order-item IDs. Partner/pool/manual subscription purchase identifiers have their own supported handling; inspect the returned result.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "orderItemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: success, removedFromCustomerAccount, removedFromDeveloperPurchases, orderId, orderItemId, customerId, productId, product, recordOnly, revokedEntitlements, revokedSerials, deactivatedActivations, message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "removedFromCustomerAccount": { "type": "boolean" }, "removedFromDeveloperPurchases": { "type": "boolean" }, "orderId": { "type": "integer", "minimum": 1 }, "orderItemId": { "type": "integer", "minimum": 1 }, "customerId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "recordOnly": { "type": "boolean" }, "revokedEntitlements": { "type": "integer" }, "revokedSerials": { "type": "integer" }, "deactivatedActivations": { "type": "integer" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "reason: string", "note: string", "deleteRecord: boolean", "mode: string", "action: string", "entitlementId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "MANUAL_GRANT_HISTORY_ONLY" ], "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js", "services/customerInformationUpdateService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" }, "deleteRecord": { "type": "boolean" }, "mode": { "type": "string" }, "action": { "type": "string" }, "entitlementId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } } } }, "/api/developer/purchases/demo-csv": { "get": { "summary": "Download the purchases import template", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/purchases/export": { "get": { "summary": "Export authorized purchases as CSV", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query dateRange: string", "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/purchases/filter-options": { "get": { "summary": "Read permitted purchase product and reseller filters", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: products, resellers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "resellers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/purchases/import": { "post": { "summary": "Import reviewed purchases rows", "description": "Send a CSV file under file or the named JSON row array. Inspect row errors on 207; do not blindly replay already imported rows. Product mappings do not bypass ownership. Customer imports require customers.manage and all-products scope; purchase imports require entitlements.manage and serial imports require serials.manage, with assigned-product checks. Purchase import does not collect payment or transfer provider billing authority and disables purchase marketing/email activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: success, importedCount, insertedCount, errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "importedCount": { "type": "integer" }, "insertedCount": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "207": { "description": "Successful idempotent replay or duplicate confirmation; inspect the linked operation contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "importedCount": { "type": "integer" }, "insertedCount": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "file: string", "purchases: array", "productMappings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "purchases": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "serialCode": { "type": "string" }, "price": { "type": "number" }, "salePrice": { "type": "number" }, "date": { "type": "string" } }, "additionalProperties": true } }, "productMappings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "purchases": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "serialCode": { "type": "string" }, "price": { "type": "number" }, "salePrice": { "type": "number" }, "date": { "type": "string" } }, "additionalProperties": true } }, "productMappings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/purchases/manual-grant": { "post": { "summary": "Grant authorized product access without collecting payment", "description": "Choose explicit products and customer identity. Existing-serial assignment and subscription grants are single-product operations. Reuse grantRequestId only for the same intended grant. A standard product grant can record manual history even when active access already exists; historyRecorded/alreadyHadAccess identify that result. Existing entitlement provenance and serials are retained; this is not a second payment, repeated marketing enrollment or a settlement credit. Subscription grants require subscriptionGrantDuration; custom also requires subscriptionGrantEndDate as YYYY-MM-DD. A timed manual keep-products grant immediately owns the included product snapshot without payment; lifetime grants remain complimentary ongoing access. Future billing requires separate payment setup, preview and customer confirmation. Explicit developer access removal can revoke the manual grant; cancellation or expiry of its subscription does not remove the timed keep-products gift.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: success, grantType, count, createdCount, skippedCount, created, grants, products, purchases, items, entitlements, serials, historyRecorded, alreadyHadAccess.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "grantType": { "type": "string" }, "count": { "type": "integer" }, "createdCount": { "type": "integer" }, "skippedCount": { "type": "integer" }, "created": { "type": "boolean" }, "grants": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "purchases": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "entitlements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true } }, "historyRecorded": { "type": "boolean" }, "alreadyHadAccess": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "productId: integer", "productIds: array", "email: string", "firstName: string", "lastName: string", "customerId: integer", "grantType: string", "grantRequestId: string", "reason: string", "note: string", "serialId: integer", "sendProductPurchaseEmails: boolean", "subscriptionGrantDuration: week | month | three_months | custom | lifetime", "subscriptionGrantEndDate: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js", "services/manualSubscriptionGrantService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "customerId": { "type": "integer", "minimum": 1 }, "grantType": { "type": "string" }, "grantRequestId": { "type": "string" }, "reason": { "type": "string" }, "note": { "type": "string" }, "serialId": { "type": "integer", "minimum": 1 }, "sendProductPurchaseEmails": { "type": "boolean" }, "subscriptionGrantDuration": { "type": "string", "enum": [ "week", "month", "three_months", "custom", "lifetime" ] }, "subscriptionGrantEndDate": { "type": "string", "format": "date" } }, "additionalProperties": true } } } } } }, "/api/developer/readiness": { "get": { "summary": "Inspect the signed-in developer account readiness", "description": "Diagnostic output, not publication or checkout activation. Read blockers, warnings, categories, evidence and action links; a percentage alone is not approval. Developer checks include billing, settlement and email configuration and can initialize/read settlement or sender state. Do not use these as a zero-write uptime probe, a provider-verification certificate or a promise of live native-host runtime verification.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/readiness" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: scope, status, goLiveReady, completionPercent, developer_id, product_id, storefront_id, generated_at, blockers, warnings, categories, blockingCount, warningCount, requiredIncompleteCount, nextAction, nextActionCode, nextActionCategory, launchChecklist, categorySummary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "enum": [ "developer", "product", "storefront" ] }, "status": { "type": "string" }, "goLiveReady": { "type": "boolean" }, "completionPercent": { "type": "number" }, "developer_id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "storefront_id": { "type": [ "integer", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "weight": { "type": "number" }, "completionPercent": { "type": "number" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "href": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "blockingCount": { "type": "integer" }, "warningCount": { "type": "integer" }, "requiredIncompleteCount": { "type": "integer" }, "nextAction": { "type": [ "string", "null" ] }, "nextActionCode": { "type": [ "string", "null" ] }, "nextActionCategory": { "type": [ "string", "null" ] }, "launchChecklist": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "categorySummary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account identity, not the selected effective workspace owner.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerReadinessRoutes.js", "services/developerReadinessService.js", "services/developerReadinessSummaryService.js" ] } }, "/api/developer/rent-to-own/agreements": { "get": { "summary": "List developer rent-to-own agreements", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/rent-to-own" }, "parameters": [ { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: agreements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "customerUserId": { "type": [ "integer", "null" ] }, "customerId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": [ "string", "null" ] }, "planVersionId": { "type": "integer", "minimum": 1 }, "checkoutId": { "type": [ "integer", "null" ] }, "entitlementId": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "providerSubscriptionId": { "type": [ "string", "null" ] }, "environment": { "type": "string" }, "status": { "type": "string" }, "accessState": { "type": "string" }, "ownershipState": { "type": "string" }, "currency": { "type": "string" }, "cashPriceCents": { "type": "integer" }, "installmentAmountCents": { "type": "integer" }, "installmentCount": { "type": "integer" }, "totalContractCents": { "type": "integer" }, "paidInstallmentCount": { "type": "integer" }, "netPaidInstallmentCount": { "type": "integer" }, "paidAmountCents": { "type": "integer" }, "refundedAmountCents": { "type": "integer" }, "disputedAmountCents": { "type": "integer" }, "currentPeriodStart": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "nextPaymentAt": { "type": [ "string", "null" ], "format": "date-time" }, "failedPaymentGraceUntil": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "ownedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "installments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "installmentNumber": { "type": "integer" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amountDueCents": { "type": "integer" }, "amountPaidCents": { "type": "integer" }, "amountRefundedCents": { "type": "integer" }, "taxAmountCents": { "type": "integer" }, "discountAmountCents": { "type": "integer" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "disputedAt": { "type": [ "string", "null" ], "format": "date-time" }, "orderId": { "type": [ "integer", "null" ] } }, "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "orders.view and all-products workspace scope.", "x-request-fields": [ "query productId: integer", "query status: string", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ] } }, "/api/developer/rent-to-own/agreements/{agreementId}": { "get": { "summary": "Read a developer agreement and installment history", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/rent-to-own" }, "parameters": [ { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: agreement.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "customerUserId": { "type": [ "integer", "null" ] }, "customerId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": [ "string", "null" ] }, "planVersionId": { "type": "integer", "minimum": 1 }, "checkoutId": { "type": [ "integer", "null" ] }, "entitlementId": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "providerSubscriptionId": { "type": [ "string", "null" ] }, "environment": { "type": "string" }, "status": { "type": "string" }, "accessState": { "type": "string" }, "ownershipState": { "type": "string" }, "currency": { "type": "string" }, "cashPriceCents": { "type": "integer" }, "installmentAmountCents": { "type": "integer" }, "installmentCount": { "type": "integer" }, "totalContractCents": { "type": "integer" }, "paidInstallmentCount": { "type": "integer" }, "netPaidInstallmentCount": { "type": "integer" }, "paidAmountCents": { "type": "integer" }, "refundedAmountCents": { "type": "integer" }, "disputedAmountCents": { "type": "integer" }, "currentPeriodStart": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "nextPaymentAt": { "type": [ "string", "null" ], "format": "date-time" }, "failedPaymentGraceUntil": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "ownedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "installments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "installmentNumber": { "type": "integer" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amountDueCents": { "type": "integer" }, "amountPaidCents": { "type": "integer" }, "amountRefundedCents": { "type": "integer" }, "taxAmountCents": { "type": "integer" }, "discountAmountCents": { "type": "integer" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "disputedAt": { "type": [ "string", "null" ], "format": "date-time" }, "orderId": { "type": [ "integer", "null" ] } }, "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "orders.view and all-products workspace scope; developer ownership is checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ] } }, "/api/developer/rent-to-own/settings": { "get": { "summary": "Read developer defaults", "description": "Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "defaultBillingInterval": { "type": "string" }, "defaultInstallmentCount": { "type": "integer" }, "minInstallmentCount": { "type": "integer" }, "maxInstallmentCount": { "type": "integer" }, "defaultPriceStrategy": { "type": "string" }, "defaultPremiumBps": { "type": "integer" }, "minCashPriceCents": { "type": "integer", "minimum": 0 }, "maxCashPriceCents": { "type": "integer", "minimum": 0 }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "promotionPolicy": { "type": "string" }, "allowEarlyPayoff": { "type": "boolean" }, "customerTermsUrl": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ] }, "put": { "summary": "Update defaults", "description": "Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "defaultBillingInterval": { "type": "string" }, "defaultInstallmentCount": { "type": "integer" }, "minInstallmentCount": { "type": "integer" }, "maxInstallmentCount": { "type": "integer" }, "defaultPriceStrategy": { "type": "string" }, "defaultPremiumBps": { "type": "integer" }, "minCashPriceCents": { "type": "integer", "minimum": 0 }, "maxCashPriceCents": { "type": "integer", "minimum": 0 }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "promotionPolicy": { "type": "string" }, "allowEarlyPayoff": { "type": "boolean" }, "customerTermsUrl": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "enabled: boolean", "defaultBillingInterval: string", "defaultInstallmentCount: integer", "minInstallmentCount: integer", "maxInstallmentCount: integer", "defaultPriceStrategy: string", "defaultPremiumBps: integer", "minCashPriceCents: integer", "maxCashPriceCents: integer", "failedPaymentGraceDays: integer", "cancellationBehavior: string", "promotionPolicy: string", "allowEarlyPayoff: boolean", "customerTermsUrl: string", "displayTitle: string", "displayDisclaimer: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "defaultBillingInterval": { "type": "string" }, "defaultInstallmentCount": { "type": "integer" }, "minInstallmentCount": { "type": "integer" }, "maxInstallmentCount": { "type": "integer" }, "defaultPriceStrategy": { "type": "string" }, "defaultPremiumBps": { "type": "integer" }, "minCashPriceCents": { "type": "integer", "minimum": 0 }, "maxCashPriceCents": { "type": "integer", "minimum": 0 }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "promotionPolicy": { "type": "string" }, "allowEarlyPayoff": { "type": "boolean" }, "customerTermsUrl": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/revenue/activity": { "get": { "summary": "Read recorded revenue and access activity", "description": "Read-only report, not payment execution or a refund action. Monetary *_cents fields are integer cents; estimated earnings are not a bank transfer. Follow returned availability and scope. Current-month charges use the current UTC calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with their own access guards.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: range, start_date, end_date, currency, environment, limit, activity, backend_gaps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "limit": { "type": "integer" }, "activity": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "source": { "type": "string" }, "source_id": { "type": [ "string", "number" ] }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "amount_cents": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "product": { "type": [ "object", "null" ] }, "status": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "backend_gaps": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "controllers/developerRevenueController.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/revenue/analytics-summary": { "get": { "summary": "Read the multi-section revenue overview", "description": "Read-only report, not payment execution or a refund action. Monetary *_cents fields are integer cents; estimated earnings are not a bank transfer. Follow returned availability and scope. Current-month charges use the current UTC calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with their own access guards.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: currency, environment, unavailable_sections, summary, windows, dashboard_metrics, current_month_charges, timeline, products, product_performance, customer_behavior, storefront_traffic, email_marketing, subscription_analytics, refunds_disputes, licensing_analytics, activity, customer_locations, calculation_rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "environment": { "type": "string" }, "unavailable_sections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } }, "summary": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "gross_revenue_cents": { "type": "integer" }, "discount_total_cents": { "type": "integer" }, "tax_collected_cents": { "type": "integer" }, "refund_total_cents": { "type": "integer" }, "chargeback_total_cents": { "type": "integer" }, "disputed_total_cents": { "type": "integer" }, "platform_fees_cents": { "type": "integer" }, "marketplace_fees_cents": { "type": "integer" }, "net_revenue_cents": { "type": "integer" }, "estimated_net_revenue_cents": { "type": "integer" }, "developer_earnings_cents": { "type": "integer" }, "affiliate_share_cents": { "type": "integer" }, "collaborator_share_cents": { "type": "integer" }, "total_orders": { "type": "integer" }, "unique_customers": { "type": "integer" }, "revenue_breakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "windows": { "type": "object", "properties": { "current_or_selected": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "gross_revenue_cents": { "type": "integer" }, "discount_total_cents": { "type": "integer" }, "tax_collected_cents": { "type": "integer" }, "refund_total_cents": { "type": "integer" }, "chargeback_total_cents": { "type": "integer" }, "disputed_total_cents": { "type": "integer" }, "platform_fees_cents": { "type": "integer" }, "marketplace_fees_cents": { "type": "integer" }, "net_revenue_cents": { "type": "integer" }, "estimated_net_revenue_cents": { "type": "integer" }, "developer_earnings_cents": { "type": "integer" }, "affiliate_share_cents": { "type": "integer" }, "collaborator_share_cents": { "type": "integer" }, "total_orders": { "type": "integer" }, "unique_customers": { "type": "integer" }, "revenue_breakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "last_30_days": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "gross_revenue_cents": { "type": "integer" }, "discount_total_cents": { "type": "integer" }, "tax_collected_cents": { "type": "integer" }, "refund_total_cents": { "type": "integer" }, "chargeback_total_cents": { "type": "integer" }, "disputed_total_cents": { "type": "integer" }, "platform_fees_cents": { "type": "integer" }, "marketplace_fees_cents": { "type": "integer" }, "net_revenue_cents": { "type": "integer" }, "estimated_net_revenue_cents": { "type": "integer" }, "developer_earnings_cents": { "type": "integer" }, "affiliate_share_cents": { "type": "integer" }, "collaborator_share_cents": { "type": "integer" }, "total_orders": { "type": "integer" }, "unique_customers": { "type": "integer" }, "revenue_breakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "previous_month": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "gross_revenue_cents": { "type": "integer" }, "discount_total_cents": { "type": "integer" }, "tax_collected_cents": { "type": "integer" }, "refund_total_cents": { "type": "integer" }, "chargeback_total_cents": { "type": "integer" }, "disputed_total_cents": { "type": "integer" }, "platform_fees_cents": { "type": "integer" }, "marketplace_fees_cents": { "type": "integer" }, "net_revenue_cents": { "type": "integer" }, "estimated_net_revenue_cents": { "type": "integer" }, "developer_earnings_cents": { "type": "integer" }, "affiliate_share_cents": { "type": "integer" }, "collaborator_share_cents": { "type": "integer" }, "total_orders": { "type": "integer" }, "unique_customers": { "type": "integer" }, "revenue_breakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true }, "dashboard_metrics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "current_month_charges": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "timeline": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "products": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "product_performance": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "customer_behavior": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "storefront_traffic": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "email_marketing": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "subscription_analytics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "refunds_disputes": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "licensing_analytics": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "activity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "customer_locations": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "calculation_rules": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "controllers/developerRevenueController.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/revenue/current-month-charges": { "get": { "summary": "Read current-month billed and usage charge estimates", "description": "Read-only report, not payment execution or a refund action. Monetary *_cents fields are integer cents; estimated earnings are not a bank transfer. Follow returned availability and scope. Current-month charges use the current UTC calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with their own access guards.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: charges.", "content": { "application/json": { "schema": { "type": "object", "properties": { "charges": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "controllers/developerRevenueController.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/revenue/marketplace": { "get": { "summary": "Read marketplace-attributed developer sale shares", "description": "Uses the share-report shape with marketplace-only filtering. Attribution is not a second SoundSync fee or proof of a completed recipient payout.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: range, start_date, end_date, currency, environment, summary, page, limit, offset, total, has_more, shares.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" }, "shares": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "order_id": { "type": "integer", "minimum": 1 }, "order_item_id": { "type": "integer", "minimum": 1 }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "sale_source": { "type": "string" }, "payment_state": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true }, "gross_amount_cents": { "type": "integer" }, "platform_fee_cents": { "type": "integer" }, "developer_share_cents": { "type": "integer" }, "reseller_share_cents": { "type": "integer" }, "currency": { "type": "string" }, "fee_model": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "controllers/developerRevenueController.js", "services/developerRevenueReportingService.js", "services/marketplaceRevenueSharingService.js" ] } }, "/api/developer/revenue/products": { "get": { "summary": "Read revenue grouped by product", "description": "Read-only report, not payment execution or a refund action. Monetary *_cents fields are integer cents; estimated earnings are not a bank transfer. Follow returned availability and scope. Current-month charges use the current UTC calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with their own access guards.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: range, start_date, end_date, currency, environment, sort, products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "sort": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "gross_revenue_cents": { "type": "integer" }, "net_revenue_cents": { "type": "integer" }, "estimated_net_revenue_cents": { "type": "integer" }, "order_count": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "controllers/developerRevenueController.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/revenue/refunds-disputes": { "get": { "summary": "Read recorded refunds and disputes", "description": "This recorded-issue list is not a refund eligibility preview. limit defaults to 50 and caps at 100. Match issue type and owned order; records can contain private purchase and ledger details.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "orderId", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateBasis", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minAmountCents", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "maxAmountCents", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "needsAttention", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: rows, pagination, filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "refund", "dispute" ] }, "status": { "type": "string" }, "order": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] } }, "additionalProperties": true }, "amount_cents": { "type": "integer" }, "reason": { "type": [ "string", "null" ] }, "entitlements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "ledger_entries": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true }, "filters": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "string" }, "q": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query type: string", "query status: string", "query q: string", "query search: string", "query orderId: string", "query productId: string", "query startDate: string", "query endDate: string", "query dateBasis: string", "query minAmountCents: string", "query maxAmountCents: string", "query needsAttention: string", "query sort: string", "query limit: string", "query offset: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "services/paymentIssueReportingService.js" ] } }, "/api/developer/revenue/refunds-disputes/{type}/{orderId}": { "get": { "summary": "Read an owned order refund or dispute with its timeline", "description": "type must be refund or dispute; orderId is the order identifier, not a refund ID. Returns 404 when the permitted issue is not found. No funds or access are changed.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: issue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "issue": { "type": "object", "properties": { "type": { "enum": [ "refund", "dispute" ] }, "status": { "type": "string" }, "order": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] } }, "additionalProperties": true }, "amount_cents": { "type": "integer" }, "reason": { "type": [ "string", "null" ] }, "entitlements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "ledger_entries": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "title": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "services/paymentIssueReportingService.js" ] } }, "/api/developer/revenue/shares": { "get": { "summary": "Read developer sale-share records", "description": "Read-only report, not payment execution or a refund action. Monetary *_cents fields are integer cents; estimated earnings are not a bank transfer. Follow returned availability and scope. Current-month charges use the current UTC calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with their own access guards.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: range, start_date, end_date, currency, environment, summary, page, limit, offset, total, has_more, shares.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" }, "shares": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "order_id": { "type": "integer", "minimum": 1 }, "order_item_id": { "type": "integer", "minimum": 1 }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "sale_source": { "type": "string" }, "payment_state": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true }, "gross_amount_cents": { "type": "integer" }, "platform_fee_cents": { "type": "integer" }, "developer_share_cents": { "type": "integer" }, "reseller_share_cents": { "type": "integer" }, "currency": { "type": "string" }, "fee_model": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer", "query page: integer", "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "controllers/developerRevenueController.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/revenue/summary": { "get": { "summary": "Read the current developer revenue summary", "description": "Read-only report, not payment execution or a refund action. Monetary *_cents fields are integer cents; estimated earnings are not a bank transfer. Follow returned availability and scope. Current-month charges use the current UTC calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with their own access guards.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "gross_revenue_cents": { "type": "integer" }, "discount_total_cents": { "type": "integer" }, "tax_collected_cents": { "type": "integer" }, "refund_total_cents": { "type": "integer" }, "chargeback_total_cents": { "type": "integer" }, "disputed_total_cents": { "type": "integer" }, "platform_fees_cents": { "type": "integer" }, "marketplace_fees_cents": { "type": "integer" }, "net_revenue_cents": { "type": "integer" }, "estimated_net_revenue_cents": { "type": "integer" }, "developer_earnings_cents": { "type": "integer" }, "affiliate_share_cents": { "type": "integer" }, "collaborator_share_cents": { "type": "integer" }, "total_orders": { "type": "integer" }, "unique_customers": { "type": "integer" }, "revenue_breakdown": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "controllers/developerRevenueController.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/revenue/timeline": { "get": { "summary": "Read revenue grouped by day, week or month", "description": "Read-only report, not payment execution or a refund action. Monetary *_cents fields are integer cents; estimated earnings are not a bank transfer. Follow returned availability and scope. Current-month charges use the current UTC calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with their own access guards.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "group", "in": "query", "schema": { "enum": [ "day", "week", "month" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: range, start_date, end_date, currency, environment, group, timeline.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "group": { "type": "string" }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string" }, "gross_revenue_cents": { "type": "integer" }, "net_revenue_cents": { "type": "integer" }, "estimated_net_revenue_cents": { "type": "integer" }, "orders": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer", "query group: value" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "controllers/developerRevenueController.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/revenue/transactions": { "get": { "summary": "Read paginated product-level sale rows", "description": "Read-only report, not payment execution or a refund action. Monetary *_cents fields are integer cents; estimated earnings are not a bank transfer. Follow returned availability and scope. Current-month charges use the current UTC calendar month, not an arbitrary requested historical range. Summary/products/activity/charges have compatible /analytics/revenue routes with their own access guards.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/revenue-reporting" }, "parameters": [ { "name": "range", "in": "query", "schema": { "enum": [ "today", "7d", "30d", "90d", "current_month", "previous_month" ] }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "usd" }, "required": false, "description": "" }, { "name": "environment", "in": "query", "schema": { "enum": [ "live", "test" ] }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: range, start_date, end_date, currency, environment, page, limit, offset, total, has_more, transactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "integer", "minimum": 1 }, "order_date": { "type": [ "string", "null" ], "format": "date-time" }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true }, "customer": { "type": [ "object", "null" ] }, "gross_amount_cents": { "type": "integer" }, "refund_amount_cents": { "type": "integer" }, "net_amount_cents": { "type": "integer" }, "estimated_net_amount_cents": { "type": "integer" }, "order_source": { "type": "string" }, "sale_channel": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "analytics.view and all-products workspace scope. Filters never expand the effective developer workspace.", "x-request-fields": [ "query range: value", "query startDate: string", "query endDate: string", "query currency: string", "query environment: value", "query productId: integer", "query page: integer", "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRevenueRoutes.js", "controllers/developerRevenueController.js", "services/developerRevenueReportingService.js" ] } }, "/api/developer/reviews": { "get": { "summary": "List product reviews visible to developer.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "rating", "in": "query", "schema": { "type": "integer" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "reviews[].", "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1, "description": "Review IDs can be serialized strings; preserve the value when using moderation routes." }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "productSlug": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "imported": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "additionalProperties": true }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "pending": { "type": "integer" }, "published": { "type": "integer" }, "hidden": { "type": "integer" }, "rejected": { "type": "integer" } }, "additionalProperties": true }, "summary": { "type": "object", "properties": { "averageRating": { "type": "number" }, "responseRate": { "type": "number" }, "responded": { "type": "integer" } }, "additionalProperties": true }, "filters": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query status: string", "query productId: integer", "query rating: integer", "query dateRange: string", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerReviewRoutes.js", "services/productReviewService.js" ] } }, "/api/developer/reviews/{reviewId}": { "patch": { "summary": "Update review moderation/status fields.", "description": "Side effects: Updates developer-owned review status/content metadata.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [ { "name": "reviewId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "updated review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1, "description": "Review IDs can be serialized strings; preserve the value when using moderation routes." }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "productSlug": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "imported": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "automation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "status: string", "action: string", "developerResponse: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerReviewRoutes.js", "services/productReviewService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "action": { "type": "string" }, "developerResponse": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/reviews/{reviewId}/{action}": { "post": { "summary": "Apply review action approve/publish/hide/reject/pending.", "description": "The route maps moderation actions to supported statuses; review rewards and notifications remain separately eligible outcomes. Side effects: Updates review moderation status.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/brand-domains-reviews" }, "parameters": [ { "name": "reviewId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "updated review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1, "description": "Review IDs can be serialized strings; preserve the value when using moderation routes." }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "productSlug": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "imported": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "automation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "developerResponse: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerReviewRoutes.js", "services/productReviewService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "developerResponse": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/reviews/import": { "post": { "summary": "Save confirmed valid non-duplicate review rows", "description": "Send the original rows and mapping again, not the previewRows response. Revalidates at commit and skips invalid/duplicate rows. Defaults to pending; allowPublished:true permits mapped publication status. Does not create an entitlement or verified-purchase badge. Inspect all outcomes; this is not an atomic batch or an idempotency-key API. Re-preview uncertain results before replay.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/review-imports" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: importBatchId, importedCount, skippedCount, counts, reviews, previewRows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "importBatchId": { "type": "string" }, "importedCount": { "type": "integer" }, "skippedCount": { "type": "integer" }, "counts": { "type": "object", "properties": { "ready": { "type": "integer" }, "invalid": { "type": "integer" }, "duplicate": { "type": "integer" } }, "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "productId": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "customerEmail": { "type": [ "string", "null" ] }, "customerId": { "type": [ "integer", "null" ] }, "imported": { "type": "boolean" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "previewRows": { "type": "array", "items": { "type": "object", "properties": { "rowNumber": { "type": "integer" }, "status": { "enum": [ "ready", "invalid", "duplicate" ] }, "productId": { "type": [ "integer", "null" ] }, "productName": { "type": "string" }, "rating": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": "string" }, "customerEmail": { "type": "string" }, "importedCreatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewStatus": { "type": "string" }, "source": { "type": "string" }, "verifiedClaim": { "type": "boolean" }, "messages": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "reviews.view plus reviews.respond and assigned-product scope.", "x-request-fields": [ "rows: array (required)", "mapping: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "allowPublished: boolean", "confirm: boolean", "confirmed: boolean", "importBatchId: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "REVIEW_IMPORT_EMPTY", "REVIEW_IMPORT_CONFIRM_REQUIRED", "REVIEW_IMPORT_NO_READY_ROWS" ], "x-source-files": [ "routes/developerReviewRoutes.js", "services/productReviewService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "oneOf": [ { "type": "object", "properties": { "product": { "type": "string" }, "rating": { "type": [ "number", "string" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "customerEmail": { "type": "string" }, "createdAt": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "verifiedClaim": { "type": [ "boolean", "string", "number" ] } }, "additionalProperties": true }, { "type": "array", "items": {} } ] } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "allowPublished": { "type": "boolean" }, "confirm": { "type": "boolean" }, "confirmed": { "type": "boolean" }, "importBatchId": { "type": "string" } }, "required": [ "rows" ], "additionalProperties": true, "anyOf": [ { "required": [ "confirm" ], "properties": { "confirm": { "const": true } } }, { "required": [ "confirmed" ], "properties": { "confirmed": { "const": true } } } ] } } } } } }, "/api/developer/reviews/import/preview": { "post": { "summary": "Validate mapped review rows without saving reviews", "description": "JSON rows only; parse CSV/XLSX before this request. Mapping values are object column names or zero-based array indexes. Only the first 1,000 rows are processed; chunk deliberately. Matches owned products and existing fingerprints. Invalid and duplicate rows are separate outcomes, not saved reviews. Imported claims of verification do not create a verified purchase. allowPublished defaults false.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/review-imports" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: counts, previewRows, products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "ready": { "type": "integer" }, "invalid": { "type": "integer" }, "duplicate": { "type": "integer" } }, "additionalProperties": true }, "previewRows": { "type": "array", "items": { "type": "object", "properties": { "rowNumber": { "type": "integer" }, "status": { "enum": [ "ready", "invalid", "duplicate" ] }, "productId": { "type": [ "integer", "null" ] }, "productName": { "type": "string" }, "rating": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": "string" }, "customerEmail": { "type": "string" }, "importedCreatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewStatus": { "type": "string" }, "source": { "type": "string" }, "verifiedClaim": { "type": "boolean" }, "messages": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "reviews.view and assigned-product scope.", "x-request-fields": [ "rows: array (required)", "mapping: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "allowPublished: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "REVIEW_IMPORT_EMPTY" ], "x-source-files": [ "routes/developerReviewRoutes.js", "services/productReviewService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "oneOf": [ { "type": "object", "properties": { "product": { "type": "string" }, "rating": { "type": [ "number", "string" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "customerEmail": { "type": "string" }, "createdAt": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "verifiedClaim": { "type": [ "boolean", "string", "number" ] } }, "additionalProperties": true }, { "type": "array", "items": {} } ] } }, "mapping": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "allowPublished": { "type": "boolean" } }, "required": [ "rows" ], "additionalProperties": true } } } } } }, "/api/developer/serials": { "get": { "summary": "Search serial inventory and device counts", "description": "Account permissions and assigned products determine scope; query filters cannot expand it. Purchase identifiers can include external/manual references; they are not all eligible managed-payment refund IDs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "available", "redeemed" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: rows, total, page, pageSize.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query dateRange: string", "query productId: integer", "query status: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/serials/{serialId}/activate": { "post": { "summary": "Apply the activate serial-access action", "description": "Changes developer-controlled serial access. It is not a provider refund, customer identity transfer or checkout payment. Revocation/suspension/deactivation can affect existing devices.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serial, deactivatedActivations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serial": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true }, "deactivatedActivations": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/serials/{serialId}/activations": { "get": { "summary": "Inspect device activations", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serial, activations, current_activations, max_activations, remaining_activations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serial": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "activations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "instance_id": { "type": "string" }, "active": { "type": "boolean" }, "status": { "type": "string" } }, "additionalProperties": true } }, "current_activations": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js", "services/customerInformationUpdateService.js" ] } }, "/api/developer/serials/{serialId}/activations/{activationId}/deactivate": { "post": { "summary": "Deactivate the selected device", "description": "Scoped administrative device release, not a refund or entitlement deletion. A changed activation can return 409.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "activationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: activation, current_activations, max_activations, remaining_activations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "activation": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "active": { "const": false }, "status": { "type": "string" } }, "additionalProperties": true }, "current_activations": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js", "services/customerInformationUpdateService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/serials/{serialId}/customer-portal-order/hide": { "post": { "summary": "Hide the supported order from customer history", "description": "Changes history presentation, not product ownership or payment/refund state.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serialId, serial, orderId, customerPortalHidden.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serialId": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "orderId": { "type": [ "integer", "string" ], "minLength": 1 }, "customerPortalHidden": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/serials/{serialId}/customer-portal-order/show": { "post": { "summary": "Show the supported order in customer history", "description": "Changes history presentation, not product ownership or payment/refund state.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serialId, serial, orderId, customerPortalHidden.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serialId": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "orderId": { "type": [ "integer", "string" ], "minLength": 1 }, "customerPortalHidden": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/serials/{serialId}/deactivate": { "post": { "summary": "Apply the deactivate serial-access action", "description": "Changes developer-controlled serial access. It is not a provider refund, customer identity transfer or checkout payment. Revocation/suspension/deactivation can affect existing devices.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serial, deactivatedActivations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serial": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true }, "deactivatedActivations": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/serials/{serialId}/reactivate": { "post": { "summary": "Apply the reactivate serial-access action", "description": "Changes developer-controlled serial access. It is not a provider refund, customer identity transfer or checkout payment. Revocation/suspension/deactivation can affect existing devices.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serial, deactivatedActivations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serial": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true }, "deactivatedActivations": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/serials/{serialId}/revoke": { "post": { "summary": "Apply the revoke serial-access action", "description": "Changes developer-controlled serial access. It is not a provider refund, customer identity transfer or checkout payment. Revocation/suspension/deactivation can affect existing devices.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serial, deactivatedActivations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serial": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true }, "deactivatedActivations": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/serials/{serialId}/suspend": { "post": { "summary": "Apply the suspend serial-access action", "description": "Changes developer-controlled serial access. It is not a provider refund, customer identity transfer or checkout payment. Revocation/suspension/deactivation can affect existing devices.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serial, deactivatedActivations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serial": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true }, "deactivatedActivations": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/serials/{serialId}/unsuspend": { "post": { "summary": "Apply the unsuspend serial-access action", "description": "Changes developer-controlled serial access. It is not a provider refund, customer identity transfer or checkout payment. Revocation/suspension/deactivation can affect existing devices.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serial, deactivatedActivations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serial": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true }, "deactivatedActivations": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "reason: string", "note: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/serials/available-by-product": { "get": { "summary": "Group available serials by product and promotion", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: products, promos, rows, total, page, pageSize.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "promos": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query dateRange: string", "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/serials/demo-csv": { "get": { "summary": "Download the serials import template", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/serials/export": { "get": { "summary": "Export authorized serials as CSV", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "productId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query dateRange: string", "query productId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/serials/generate": { "post": { "summary": "Generate unique serials for an owned product", "description": "product_id and corresponding snake_case date/price aliases remain accepted. Use Partners > Licenses for reseller serial pools; reseller assignment on this route returns PARTNER_POOL_REQUIRED. Existing billing and product-scope checks apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: message, count, product, serials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "count": { "type": "integer" }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "serial": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "product": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "active_activation_count": { "type": "integer" }, "max_activations": { "type": "integer" }, "remaining_activations": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "productId: integer", "product_id: integer", "quantity: integer (required)", "prefix: string", "expiresAt: string,null", "promoPrice: number", "promoStart: string,null", "promoExpires: string,null", "activeFrom: string,null", "activeTo: string,null", "batchTag: string", "notes: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "prefix": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "promoPrice": { "type": "number" }, "promoStart": { "type": [ "string", "null" ], "format": "date-time" }, "promoExpires": { "type": [ "string", "null" ], "format": "date-time" }, "activeFrom": { "type": [ "string", "null" ], "format": "date-time" }, "activeTo": { "type": [ "string", "null" ], "format": "date-time" }, "batchTag": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "quantity" ], "additionalProperties": true, "anyOf": [ { "required": [ "productId" ] }, { "required": [ "product_id" ] } ] } } } } } }, "/api/developer/serials/import": { "post": { "summary": "Import reviewed serials rows", "description": "Send a CSV file under file or the named JSON row array. Inspect row errors on 207; do not blindly replay already imported rows. Product mappings do not bypass ownership. Customer imports require customers.manage and all-products scope; purchase imports require entitlements.manage and serial imports require serials.manage, with assigned-product checks. Purchase import does not collect payment or transfer provider billing authority and disables purchase marketing/email activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: success, importedCount, insertedCount, errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "importedCount": { "type": "integer" }, "insertedCount": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "207": { "description": "Successful idempotent replay or duplicate confirmation; inspect the linked operation contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "importedCount": { "type": "integer" }, "insertedCount": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "file: string", "serials: array", "productMappings: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "serialCode": { "type": "string" }, "price": { "type": "number" }, "salePrice": { "type": "number" }, "date": { "type": "string" } }, "additionalProperties": true } }, "productMappings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "serialCode": { "type": "string" }, "price": { "type": "number" }, "salePrice": { "type": "number" }, "date": { "type": "string" } }, "additionalProperties": true } }, "productMappings": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/serials/resellers": { "get": { "summary": "List eligible relationship and legacy reseller references", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: resellers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resellers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "name": { "type": "string" }, "kind": { "type": "string" }, "relationship_id": { "type": "integer", "minimum": 1 }, "developer_share_bps": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerCustomerSerialRoutes.js", "services/developerCustomerSerialService.js" ] } }, "/api/developer/settlements/adjustments-v2": { "get": { "summary": "Read allocations defaulting to negative-adjustment state", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. These allocation lists do not implement environment or date-range filters; do not assume summary-v2 filters apply. settlement_account_id aliases settlementAccountId. The server fixes developerId. A supplied valid state overrides the endpoint default. There is no hasMore or total field: continue offset paging until a short page. These are allocation rows, not bank-payout confirmations.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "settlementAccountId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "pending_hold", "held", "dispute_hold", "available", "reserved_for_batch", "approved_for_transfer", "partially_transferred", "transferred", "negative_adjustment", "reversed", "partially_reversed", "canceled", "invalidated" ], "default": "negative_adjustment" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: allocations, limit, offset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "settlement_account_id": { "type": [ "integer", "string" ] }, "order_id": { "type": [ "integer", "string" ] }, "state": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "remaining_amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "allocation_basis_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "platform_share_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "tax_excluded_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "available_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query limit: integer", "query offset: integer", "query currency: string", "query settlementAccountId: integer", "query state: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "INVALID_ALLOCATION_STATE", "JOURNAL_SETTLEMENT_TABLES_MISSING" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/journalSettlementService.js", "services/revenueReportingScope.js" ] } }, "/api/developer/settlements/balance": { "get": { "summary": "Fetch settlement balance and payout account state.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [], "responses": { "200": { "description": "balance/account payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "party_type": { "type": "string" }, "party_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "payout_method_status": { "type": "string" }, "currency": { "type": "string" }, "available_balance_cents": { "type": "integer" }, "pending_balance_cents": { "type": "integer" }, "lifetime_earned_cents": { "type": "integer" }, "lifetime_paid_cents": { "type": "integer" }, "lifetime_refunded_cents": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "payout_status_refreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "services/payoutSettlementService.js" ] } }, "/api/developer/settlements/bank-payouts": { "get": { "summary": "Read provider bank-payout records for the workspace", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Reports saved provider records, not a fresh Stripe lookup. pending/in_transit is not paid; an arrival estimate is not confirmed bank receipt.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Defaults to usd. Current commerce operates in USD." }, { "name": "environment", "in": "query", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: payouts, limit, offset, hasMore, currency, environment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "payouts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "provider_payout_id": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "arrival_date": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "currency": { "type": "string" }, "environment": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string. Defaults to usd. Current commerce operates in USD.", "query environment: string", "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/connectPayoutService.js" ] } }, "/api/developer/settlements/batches": { "get": { "summary": "List settlement batches.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "batches[].", "content": { "application/json": { "schema": { "type": "object", "properties": { "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "currency": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "item_count": { "type": "integer" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "provider": { "type": "string" }, "provider_batch_id": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "services/payoutSettlementService.js" ] } }, "/api/developer/settlements/connect-session": { "post": { "summary": "Create Stripe Connect payout onboarding/session.", "description": "Only the workspace owner may create or resume Stripe Connect onboarding. Requires billing.view, all-products scope and server-resolved isWorkspaceOwner:true; a role name, permission list or request-body owner flag cannot substitute. Non-owners receive 403 developer_team_owner_required before provider or onboarding-approval checks. Live mode still requires the configured onboarding approval; this call cannot enable it. /earnings/connect-session and /payouts/connect-session are compatibility aliases with the same guard. Billing/Administrator reporting and payout-status refresh retain their existing billing permissions. An onboarding URL is not a transfer or proof that payouts completed; no execution flag is changed. Side effects: Creates Stripe Connect account link/session.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [], "responses": { "200": { "description": "Connect session URL/metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "provider": { "type": "string" }, "stripe_mode": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace owner only, with billing.view and all-products scope; live onboarding approval remains required.", "x-request-fields": [ "returnTo: string", "collectionFields: currently_due | eventually_due", "environment: test | live" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "developer_team_owner_required", "developer_team_all_products_scope_required", "LIVE_CONNECT_DEVELOPER_NOT_ALLOWLISTED" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/payoutSettlementService.js", "services/livePilotPolicyService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnTo": { "type": "string" }, "collectionFields": { "type": "string", "enum": [ "currently_due", "eventually_due" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] } }, "additionalProperties": true } } } } } }, "/api/developer/settlements/history": { "get": { "summary": "Read payout batches, transfers, bank status and uninvoiced usage", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Filters from/to select batch creation, not sale dates. hasMore requires the next offset page. unstatementedUsage contains approximate past usage not yet invoiced, only for live USD; it is not a newly issued invoice or collected charge. /payouts/history is an alias under the same router.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Defaults to usd. Current commerce operates in USD." }, { "name": "environment", "in": "query", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "required": false, "description": "" }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "required": false, "description": "Inclusive UTC batch-creation date." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "required": false, "description": "Inclusive UTC batch-creation date; must not precede from." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: batches, hasMore, limit, offset, currency, environment, unstatementedUsage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "scheduled_run_date": { "type": [ "string", "null" ] }, "first_sale_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_sale_at": { "type": [ "string", "null" ], "format": "date-time" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "internal_billing_offset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "status": { "type": "string" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "reserve_cents": { "type": [ "integer", "string", "null" ] }, "adjustment_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "billing_offset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "reference": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "reconciliation_required": { "type": [ "boolean", "null" ] }, "bank_payment": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "arrival_date": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true } }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "currency": { "type": "string" }, "environment": { "type": "string" }, "unstatementedUsage": { "type": "array", "items": { "type": "object", "properties": { "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "const": "usd" }, "status": { "const": "not_invoiced" }, "approximate": { "const": true }, "marketing_email_quantity": { "type": "integer" }, "external_redemption_quantity": { "type": "integer" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string. Defaults to usd. Current commerce operates in USD.", "query environment: string", "query from: string. Inclusive UTC batch-creation date.", "query to: string. Inclusive UTC batch-creation date; must not precede from.", "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/payoutHistoryReportingService.js", "services/revenueReportingScope.js" ] } }, "/api/developer/settlements/history/export.csv": { "get": { "summary": "Download all matching payout-history rows", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Streams all matching batches in internal pages of 100; caller limit/offset do not truncate the export. Filename: soundsync-payout-history.csv. Columns are Batch, Currency, First sale UTC, Last sale UTC, Scheduled run, Batch earnings cents, Batch status, Invoice offset cents, Transfer reference, Transfer amount cents, Transfer status, Bank reference and Bank status. Multiple transfers produce multiple rows. CSV has no unstatementedUsage projection. A mid-stream failure can terminate the download; do not treat a partial file as complete.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Defaults to usd. Current commerce operates in USD." }, { "name": "environment", "in": "query", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "required": false, "description": "" }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "required": false, "description": "Inclusive UTC batch-creation date." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "required": false, "description": "Inclusive UTC batch-creation date; must not precede from." } ], "responses": { "200": { "description": "HTTP 200: text/csv.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string. Defaults to usd. Current commerce operates in USD.", "query environment: string", "query from: string. Inclusive UTC batch-creation date.", "query to: string. Inclusive UTC batch-creation date; must not precede from." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/payoutHistoryReportingService.js", "services/revenueReportingScope.js" ] } }, "/api/developer/settlements/ledger": { "get": { "summary": "List settlement ledger.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "ledger entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "source_type": { "type": "string" }, "source_id": { "type": "integer", "minimum": 1 }, "source_reference": { "type": "string" }, "direction": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": "integer" }, "available_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [ "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "services/payoutSettlementService.js" ] } }, "/api/developer/settlements/payout-readiness": { "get": { "summary": "Fetch payout readiness.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [], "responses": { "200": { "description": "payout status booleans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "party_type": { "type": "string" }, "party_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "payout_method_status": { "type": "string" }, "payout_ready": { "type": "boolean" }, "payout_blocked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "services/payoutSettlementService.js" ] } }, "/api/developer/settlements/payout-status/refresh": { "post": { "summary": "Refresh the saved Stripe Connect payout status", "description": "Uses the configured environment when omitted; stripeEnvironment and stripe_environment alias environment. Can create a local settlement account, contact Stripe and persist status/balances. refreshed:false means no matching Connect account or provider configuration, not payout completion. refreshed:true confirms a status refresh only. This does not create an onboarding link, transfer money or enable automatic execution. /earnings and /payouts mounts are compatibility aliases.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: account, refreshed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "party_type": { "type": "string" }, "party_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "currency": { "type": "string" }, "available_balance_cents": { "type": "integer" }, "pending_balance_cents": { "type": "integer" }, "lifetime_earned_cents": { "type": "integer" }, "lifetime_paid_cents": { "type": "integer" }, "lifetime_refunded_cents": { "type": "integer" }, "payout_method_status": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "refreshed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products scope; effective developer ownership. Live onboarding approval is checked.", "x-request-fields": [ "environment: live | test" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "LIVE_CONNECT_DEVELOPER_NOT_ALLOWLISTED", "STRIPE_CONNECT_ENVIRONMENT_MISMATCH" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "services/payoutSettlementService.js", "services/livePilotPolicyService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "enum": [ "live", "test" ] } }, "additionalProperties": true } } } } } }, "/api/developer/settlements/recovery/cases": { "get": { "summary": "List owned refund/dispute recovery cases", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. No hasMore or total field is returned; continue until a short page. Missing required recovery tables is a service error.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "caseType", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "orderId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "recoveryCaseId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "settlementAccountId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 50 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: cases, limit, offset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "settlement_account_id": { "type": [ "integer", "string" ] }, "order_id": { "type": [ "integer", "string" ] }, "case_type": { "type": "string" }, "status": { "type": "string" }, "provider": { "type": "string" }, "provider_object_type": { "type": "string" }, "provider_object_id": { "type": "string" }, "currency": { "type": "string" }, "developer_recovery_target_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "developer_recovered_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "developer_outstanding_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "requested_refund_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "refunded_customer_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string", "query status: string", "query caseType: string", "query orderId: integer", "query recoveryCaseId: integer", "query settlementAccountId: integer", "query limit: integer", "query offset: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "MOR_RECOVERY_TABLES_MISSING" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/morRecoveryService.js" ] } }, "/api/developer/settlements/recovery/cases/{id}": { "get": { "summary": "Read one owned recovery case, components and safe action summaries", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. Unknown or foreign IDs return 404 RECOVERY_CASE_NOT_FOUND. Actions expose only their safe summary fields, not private execution payloads.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: case, components, actions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "settlement_account_id": { "type": [ "integer", "string" ] }, "order_id": { "type": [ "integer", "string" ] }, "case_type": { "type": "string" }, "status": { "type": "string" }, "provider": { "type": "string" }, "provider_object_type": { "type": "string" }, "provider_object_id": { "type": "string" }, "currency": { "type": "string" }, "developer_recovery_target_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "developer_recovered_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "developer_outstanding_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "requested_refund_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "refunded_customer_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "recovery_case_id": { "type": [ "integer", "string" ] }, "component_type": { "type": "string" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "currency": { "type": "string" }, "responsible_party": { "type": "string" }, "recoverable": { "type": "boolean" }, "status": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "action_type": { "type": "string" }, "status": { "type": "string" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "currency": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "RECOVERY_CASE_NOT_FOUND", "MOR_RECOVERY_TABLES_MISSING" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/morRecoveryService.js" ] } }, "/api/developer/settlements/recovery/offsets": { "get": { "summary": "Read the non-executing recovery offsets envelope", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. Currently returns offsets:[] and source:mor_recovery_safe_off. Empty output is not evidence that recovery was executed or that all outstanding obligations were cleared.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "caseType", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "orderId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "recoveryCaseId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "settlementAccountId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: offsets, summary, source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "offsets": { "type": "array", "maxItems": 0 }, "summary": { "type": "object", "properties": { "case_count": { "type": "integer" }, "target_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "recovered_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "outstanding_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "tax_reversed_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "platform_reversed_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "reserve_held_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "future_offset_pending_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." } }, "additionalProperties": true }, "source": { "const": "mor_recovery_safe_off" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string", "query status: string", "query caseType: string", "query orderId: integer", "query recoveryCaseId: integer", "query settlementAccountId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/morRecoveryService.js" ] } }, "/api/developer/settlements/recovery/reserve": { "get": { "summary": "Read existing workspace reserve records", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Lists saved records across the effective workspace; currency/environment/date filters and offset are not implemented here. This read does not establish a routine reserve policy, place a hold or release funds.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 50 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: reserves, limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reserves": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "held_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "released_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "currency": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "limit": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "MOR_RECOVERY_TABLES_MISSING" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/morRecoveryService.js" ] } }, "/api/developer/settlements/recovery/statements": { "get": { "summary": "Read the non-executing recovery statements envelope", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. Currently returns statements:[] and source:mor_recovery_safe_off. Empty output is not evidence that recovery was executed or that all outstanding obligations were cleared.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "caseType", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "orderId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "recoveryCaseId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "settlementAccountId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: statements, summary, source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statements": { "type": "array", "maxItems": 0 }, "summary": { "type": "object", "properties": { "case_count": { "type": "integer" }, "target_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "recovered_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "outstanding_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "tax_reversed_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "platform_reversed_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "reserve_held_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "future_offset_pending_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." } }, "additionalProperties": true }, "source": { "const": "mor_recovery_safe_off" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string", "query status: string", "query caseType: string", "query orderId: integer", "query recoveryCaseId: integer", "query settlementAccountId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/morRecoveryService.js" ] } }, "/api/developer/settlements/recovery/summary": { "get": { "summary": "Read recovery readiness, totals and current records", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. Missing recovery tables return ready:false with empty records; this is unavailable coverage, not verified absence of obligations. Summary filters do not turn the limited cases/reserves lists into exhaustive exports.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "caseType", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "orderId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "recoveryCaseId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "settlementAccountId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: ready, flags, summary, cases, account, reserves.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "flags": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "summary": { "type": "object", "properties": { "case_count": { "type": "integer" }, "target_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "recovered_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "outstanding_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "tax_reversed_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "platform_reversed_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "reserve_held_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "future_offset_pending_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." } }, "additionalProperties": true }, "cases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "settlement_account_id": { "type": [ "integer", "string" ] }, "order_id": { "type": [ "integer", "string" ] }, "case_type": { "type": "string" }, "status": { "type": "string" }, "provider": { "type": "string" }, "provider_object_type": { "type": "string" }, "provider_object_id": { "type": "string" }, "currency": { "type": "string" }, "developer_recovery_target_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "developer_recovered_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "developer_outstanding_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "requested_refund_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "refunded_customer_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "account": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "reserves": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string", "query status: string", "query caseType: string", "query orderId: integer", "query recoveryCaseId: integer", "query settlementAccountId: integer", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/morRecoveryService.js" ] } }, "/api/developer/settlements/settlements-v2": { "get": { "summary": "Read allocations defaulting to approved-for-transfer state", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. These allocation lists do not implement environment or date-range filters; do not assume summary-v2 filters apply. settlement_account_id aliases settlementAccountId. The server fixes developerId. A supplied valid state overrides the endpoint default. There is no hasMore or total field: continue offset paging until a short page. These are allocation rows, not bank-payout confirmations.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "settlementAccountId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "pending_hold", "held", "dispute_hold", "available", "reserved_for_batch", "approved_for_transfer", "partially_transferred", "transferred", "negative_adjustment", "reversed", "partially_reversed", "canceled", "invalidated" ], "default": "approved_for_transfer" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: allocations, limit, offset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "settlement_account_id": { "type": [ "integer", "string" ] }, "order_id": { "type": [ "integer", "string" ] }, "state": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "remaining_amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "allocation_basis_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "platform_share_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "tax_excluded_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "available_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query limit: integer", "query offset: integer", "query currency: string", "query settlementAccountId: integer", "query state: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "INVALID_ALLOCATION_STATE", "JOURNAL_SETTLEMENT_TABLES_MISSING" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/journalSettlementService.js", "services/revenueReportingScope.js" ] } }, "/api/developer/settlements/statements-v2": { "get": { "summary": "Read the journal statement-preview envelope", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Currently returns statements:[] with the summary and source:journal_settlement_preview. It does not produce statement documents. Use the developer billing statement/invoice APIs for issued billing documents; preserve the preview label.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Defaults to usd. Current commerce operates in USD." }, { "name": "environment", "in": "query", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Inclusive timestamp/date; start_date, from and periodStart/period_start are aliases." }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Exclusive timestamp; a date-only value includes that UTC day. end_date, to and periodEnd/period_end are aliases." }, { "name": "includePeriodCharges", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: statements, summary, source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statements": { "type": "array", "maxItems": 0 }, "summary": { "type": "object", "properties": { "currency": { "type": "string" }, "environment": { "type": "string" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "gross_product_revenue_before_tax_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "tax_added_to_customer_payment_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "soundsync_fee_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "developer_earnings_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "pending_hold_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "available_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "approved_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "sent_to_stripe_account_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "next_hold_release_at": { "type": [ "string", "null" ], "format": "date-time" }, "outstanding_refund_debt_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "payout_reconciliation_required": { "type": "boolean" }, "revenue_math_source": { "type": "string" }, "accounting_label": { "type": "string" }, "legacy_label": { "type": "string" }, "tax_notice": { "type": "string" }, "commerce_summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "period_charges": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "source": { "const": "journal_settlement_preview" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string. Defaults to usd. Current commerce operates in USD.", "query environment: string", "query startDate: string. Inclusive timestamp/date; start_date, from and periodStart/period_start are aliases.", "query endDate: string. Exclusive timestamp; a date-only value includes that UTC day. end_date, to and periodEnd/period_end are aliases.", "query includePeriodCharges: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "JOURNAL_SETTLEMENT_TABLES_MISSING" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/journalSettlementService.js", "services/revenueReportingScope.js" ] } }, "/api/developer/settlements/summary": { "get": { "summary": "Read settlement, transfer and bank-payment totals with the payout schedule", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. The schedule uses the server current time; this route does not forward asOf or date-range queries. A transfer to a connected account and a bank payout are distinct states. External partner sales are separately classified estimates, not funded managed-checkout balances; partnerSales.unavailable indicates missing reporting, including test scope. Neither this read nor its returned execution-status fields enables automatic payments.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Defaults to usd. Current commerce operates in USD." }, { "name": "environment", "in": "query", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: summary, partnerSales.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "available_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "held_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "reserved_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "approved_allocation_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "approved_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "transferred_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "failed_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "bank_payout_pending_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "bank_payout_paid_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "bank_payout_failed_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "currency": { "type": "string" }, "environment": { "type": "string" }, "payout_mode": { "type": "string" }, "automatic_payments_enabled": { "type": "boolean" }, "owner_transfer_execution_enabled": { "type": "boolean" }, "hold_days": { "type": "integer" }, "period_time_zone": { "type": "string" }, "schedule_time_zone": { "type": "string" }, "next_hold_release_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_payout_run_date": { "type": "string" }, "scheduled_payout_execution_at": { "type": [ "string", "null" ], "format": "date-time" }, "eligible_sale_cutoff_at": { "type": [ "string", "null" ], "format": "date-time" }, "previous_payout_run_date": { "type": "string" }, "following_payout_run_date": { "type": "string" }, "eligible_sales_period_start_date": { "type": "string" }, "eligible_sales_period_end_date": { "type": "string" }, "eligible_sales_period_exclusive_end_date": { "type": "string" } }, "additionalProperties": true }, "partnerSales": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string. Defaults to usd. Current commerce operates in USD.", "query environment: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/transferIntentService.js", "services/externalPartnerSalesReportingService.js" ] } }, "/api/developer/settlements/summary-v2": { "get": { "summary": "Read journal-derived earnings and optional period charges", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Reads preserve the returned accounting_label, legacy_label and revenue_math_source; a preview is not a cutover or transfer. A complete start/end range adds commerce-summary fields. includePeriodCharges=true requires that complete range and adds a period-charge report, not an invoice or collection. Returned flags are descriptive and do not change configuration.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Defaults to usd. Current commerce operates in USD." }, { "name": "environment", "in": "query", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "required": false, "description": "" }, { "name": "startDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Inclusive timestamp/date; start_date, from and periodStart/period_start are aliases." }, { "name": "endDate", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Exclusive timestamp; a date-only value includes that UTC day. end_date, to and periodEnd/period_end are aliases." }, { "name": "includePeriodCharges", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: summary, flags.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "currency": { "type": "string" }, "environment": { "type": "string" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "gross_product_revenue_before_tax_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "tax_added_to_customer_payment_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "soundsync_fee_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "developer_earnings_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "pending_hold_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "available_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "approved_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "sent_to_stripe_account_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "next_hold_release_at": { "type": [ "string", "null" ], "format": "date-time" }, "outstanding_refund_debt_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "payout_reconciliation_required": { "type": "boolean" }, "revenue_math_source": { "type": "string" }, "accounting_label": { "type": "string" }, "legacy_label": { "type": "string" }, "tax_notice": { "type": "string" }, "commerce_summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "period_charges": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "flags": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string. Defaults to usd. Current commerce operates in USD.", "query environment: string", "query startDate: string. Inclusive timestamp/date; start_date, from and periodStart/period_start are aliases.", "query endDate: string. Exclusive timestamp; a date-only value includes that UTC day. end_date, to and periodEnd/period_end are aliases.", "query includePeriodCharges: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "JOURNAL_SETTLEMENT_TABLES_MISSING" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/journalSettlementService.js", "services/revenueReportingScope.js" ] } }, "/api/developer/settlements/transactions-v2": { "get": { "summary": "Read journal source allocations", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. These allocation lists do not implement environment or date-range filters; do not assume summary-v2 filters apply. settlement_account_id aliases settlementAccountId. The server fixes developerId. A supplied valid state overrides the endpoint default. There is no hasMore or total field: continue offset paging until a short page. These are allocation rows, not bank-payout confirmations.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "settlementAccountId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "pending_hold", "held", "dispute_hold", "available", "reserved_for_batch", "approved_for_transfer", "partially_transferred", "transferred", "negative_adjustment", "reversed", "partially_reversed", "canceled", "invalidated" ] }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: allocations, limit, offset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "settlement_account_id": { "type": [ "integer", "string" ] }, "order_id": { "type": [ "integer", "string" ] }, "state": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "remaining_amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "allocation_basis_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "platform_share_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "tax_excluded_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "available_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query limit: integer", "query offset: integer", "query currency: string", "query settlementAccountId: integer", "query state: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "INVALID_ALLOCATION_STATE", "JOURNAL_SETTLEMENT_TABLES_MISSING" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/journalSettlementService.js", "services/revenueReportingScope.js" ] } }, "/api/developer/settlements/transfers": { "get": { "summary": "List owned payout transfer intents", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. connect_account aliases connectAccount. Queued, submitted, failed and completed records must retain their actual status. hasMore uses an extra row. Listing an intent does not approve, retry, cancel or execute it.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Defaults to usd. Current commerce operates in USD." }, { "name": "environment", "in": "query", "schema": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "required": false, "description": "" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "connectAccount", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: transfers, limit, offset, hasMore, currency, environment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "settlement_batch_id": { "type": [ "integer", "string" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "source_balance_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "reserve_amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "adjustment_amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "net_transfer_amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "provider_transfer_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "currency": { "type": "string" }, "environment": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [ "query currency: string. Defaults to usd. Current commerce operates in USD.", "query environment: string", "query limit: integer", "query offset: integer", "query status: string", "query connectAccount: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/transferIntentService.js" ] } }, "/api/developer/settlements/transfers/{id}": { "get": { "summary": "Read one transfer intent owned by the current workspace", "description": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Unknown or foreign IDs return 404 TRANSFER_INTENT_NOT_FOUND. This ID-based read does not apply currency/environment query filters; inspect the returned owned record. No transfer action is performed.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/billing" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: intent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "intent": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "developer_id": { "type": [ "integer", "string" ] }, "settlement_batch_id": { "type": [ "integer", "string" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "source_balance_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "reserve_amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "adjustment_amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "net_transfer_amount_cents": { "type": [ "integer", "string" ], "description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings." }, "provider_transfer_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "TRANSFER_INTENT_NOT_FOUND" ], "x-source-files": [ "routes/developerSettlementRoutes.js", "middleware/developerTeamAuth.js", "services/transferIntentService.js" ] } }, "/api/developer/storefront": { "get": { "summary": "Read saved storefront configuration", "description": "Returns storefront:null when absent. This is private configuration, including metadata and saved navigation, not the public catalog.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_user_id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "status": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "banner_url": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "accent_color": { "type": [ "string", "null" ] }, "theme_mode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js" ] }, "patch": { "summary": "Save storefront identity, layout and navigation", "description": "Read the current configuration first. Send siteStructure.revision when changing the structure; stale revisions or concurrent structure writes return 409 STOREFRONT_EDIT_CONFLICT. Keep unsaved edits, reload and reconcile rather than blindly retrying. Saving structure records up to 50 historical snapshots; this is not an unlimited backup guarantee.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: storefront, updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_user_id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "status": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "banner_url": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "accent_color": { "type": [ "string", "null" ] }, "theme_mode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "updated": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [ "slug: string", "status: draft | published | hidden | suspended", "displayName: string", "headline: string", "description: string", "logoUrl: string,null", "bannerUrl: string,null", "websiteUrl: string,null", "supportUrl: string,null", "primaryColor: string", "accentColor: string", "themeMode: light | dark | system", "websiteTemplate: string", "visualStyle: string", "navMode: string", "siteStructure: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "pageTemplates: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "homepageMerchandising: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "templateContentSlots: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden", "suspended" ] }, "displayName": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "bannerUrl": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "supportUrl": { "type": [ "string", "null" ] }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "themeMode": { "type": "string", "enum": [ "light", "dark", "system" ] }, "websiteTemplate": { "type": "string" }, "visualStyle": { "type": "string" }, "navMode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } }, "post": { "summary": "Create the storefront or update an existing one", "description": "201 means created; an existing storefront follows the update path with 200 and updated:true. CamelCase and supported snake_case fields are accepted. A saved draft is not a published storefront.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "Successful idempotent replay or duplicate confirmation; inspect the linked operation contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_user_id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "status": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "banner_url": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "accent_color": { "type": [ "string", "null" ] }, "theme_mode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "created": { "type": "boolean" }, "updated": { "type": "boolean" } }, "additionalProperties": true } } } }, "201": { "description": "HTTP 201: storefront, created, updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_user_id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "status": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "banner_url": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "accent_color": { "type": [ "string", "null" ] }, "theme_mode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "created": { "type": "boolean" }, "updated": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [ "slug: string", "status: draft | published | hidden | suspended", "displayName: string", "headline: string", "description: string", "logoUrl: string,null", "bannerUrl: string,null", "websiteUrl: string,null", "supportUrl: string,null", "primaryColor: string", "accentColor: string", "themeMode: light | dark | system", "websiteTemplate: string", "visualStyle: string", "navMode: string", "siteStructure: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "pageTemplates: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "homepageMerchandising: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "templateContentSlots: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden", "suspended" ] }, "displayName": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "bannerUrl": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "supportUrl": { "type": [ "string", "null" ] }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "themeMode": { "type": "string", "enum": [ "light", "dark", "system" ] }, "websiteTemplate": { "type": "string" }, "visualStyle": { "type": "string" }, "navMode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/storefront-domain": { "get": { "summary": "Read website routing and SSL readiness", "description": "A legacy verified record with no saved check can trigger provider verification and persist a fresh complete result. This GET is not guaranteed zero-write. Inspect DNS, SSL and routing checks independently, not only the top-level saved status.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: domain, settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "developerUserId": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsStatus": { "type": "string" }, "sslStatus": { "type": "string" }, "hostResolutionStatus": { "type": "string" }, "apiRoutingStatus": { "type": "string" }, "customerLoginStatus": { "type": "string" }, "libraryAccessStatus": { "type": "string" }, "checkoutReturnStatus": { "type": "string" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "record": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } }, "provider": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "settings": { "type": "object", "properties": { "target": { "type": "string" }, "proxyHost": { "type": "string" }, "expectedDnsRecords": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } }, "ready": { "type": "boolean" }, "checkoutReturnPath": { "type": "string" }, "customerLoginPath": { "type": "string" }, "libraryAccessPath": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerStorefrontDomainRoutes.js", "services/developerStorefrontDomainService.js" ] }, "post": { "summary": "Connect an apex or subdomain for the storefront", "description": "Send domain or the supported aliases. Requires domain/DNS control. Records and provider setup come from the response; do not hard-code provider DNS targets. External registration/checks can occur. This website-specific workflow does not verify email sending.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: domain, settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "developerUserId": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsStatus": { "type": "string" }, "sslStatus": { "type": "string" }, "hostResolutionStatus": { "type": "string" }, "apiRoutingStatus": { "type": "string" }, "customerLoginStatus": { "type": "string" }, "libraryAccessStatus": { "type": "string" }, "checkoutReturnStatus": { "type": "string" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "record": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } }, "provider": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "settings": { "type": "object", "properties": { "target": { "type": "string" }, "proxyHost": { "type": "string" }, "expectedDnsRecords": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } }, "ready": { "type": "boolean" }, "checkoutReturnPath": { "type": "string" }, "customerLoginPath": { "type": "string" }, "libraryAccessPath": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view, domains.manage and all-products scope.", "x-request-fields": [ "domain: string", "storefrontDomain: string", "customDomain: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontDomainRoutes.js", "services/developerStorefrontDomainService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "storefrontDomain": { "type": "string" }, "customDomain": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/storefront-domain/{domainId}/refresh": { "post": { "summary": "Refresh website DNS, routing and SSL checks", "description": "Domain ID must belong to the effective developer. Performs provider/DNS checks and persists the result. Read settings.ready and the individual states; no propagation or certificate completion time is guaranteed.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/domain-setup" }, "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: domain, settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "developerUserId": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsStatus": { "type": "string" }, "sslStatus": { "type": "string" }, "hostResolutionStatus": { "type": "string" }, "apiRoutingStatus": { "type": "string" }, "customerLoginStatus": { "type": "string" }, "libraryAccessStatus": { "type": "string" }, "checkoutReturnStatus": { "type": "string" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "record": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } }, "provider": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "settings": { "type": "object", "properties": { "target": { "type": "string" }, "proxyHost": { "type": "string" }, "expectedDnsRecords": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } }, "ready": { "type": "boolean" }, "checkoutReturnPath": { "type": "string" }, "customerLoginPath": { "type": "string" }, "libraryAccessPath": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "domains.view, domains.manage and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerStorefrontDomainRoutes.js", "services/developerStorefrontDomainService.js" ] } }, "/api/developer/storefront/ai/banner": { "post": { "summary": "Generate a storefront banner draft", "description": "Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": [ "integer", "string", "null" ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [ "currentStorefront: object", "notes: string", "instructions: string", "mood: string", "visualMood: string", "tone: string", "targetCustomer: string", "bannerUse: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js", "services/storefrontAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentStorefront": { "type": "object", "properties": { "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden", "suspended" ] }, "displayName": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "bannerUrl": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "supportUrl": { "type": [ "string", "null" ] }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "themeMode": { "type": "string", "enum": [ "light", "dark", "system" ] }, "websiteTemplate": { "type": "string" }, "visualStyle": { "type": "string" }, "navMode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "mood": { "type": "string" }, "visualMood": { "type": "string" }, "tone": { "type": "string" }, "targetCustomer": { "type": "string" }, "bannerUse": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/storefront/ai/copy": { "post": { "summary": "Generate a storefront copy draft", "description": "Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": [ "integer", "string", "null" ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [ "currentStorefront: object", "notes: string", "instructions: string", "mood: string", "visualMood: string", "tone: string", "targetCustomer: string", "bannerUse: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js", "services/storefrontAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentStorefront": { "type": "object", "properties": { "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden", "suspended" ] }, "displayName": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "bannerUrl": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "supportUrl": { "type": [ "string", "null" ] }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "themeMode": { "type": "string", "enum": [ "light", "dark", "system" ] }, "websiteTemplate": { "type": "string" }, "visualStyle": { "type": "string" }, "navMode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "mood": { "type": "string" }, "visualMood": { "type": "string" }, "tone": { "type": "string" }, "targetCustomer": { "type": "string" }, "bannerUse": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/storefront/ai/drafts": { "get": { "summary": "List the latest 50 storefront AI drafts", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: drafts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "drafts": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "storefront_id": { "type": [ "integer", "string", "null" ] }, "tool_type": { "type": "string" }, "generated_payload_json": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "generated_asset_id": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js", "services/storefrontAiService.js" ] } }, "/api/developer/storefront/ai/drafts/{draftId}/applied": { "post": { "summary": "Mark a storefront draft applied", "description": "Developer-scoped review status only. Does not apply content, publish a website or physically delete an asset. These IDs are not operational or product-setup draft IDs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [ { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "storefront_id": { "type": [ "integer", "string", "null" ] }, "tool_type": { "type": "string" }, "generated_payload_json": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "generated_asset_id": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js", "services/storefrontAiService.js" ] } }, "/api/developer/storefront/ai/drafts/{draftId}/discard": { "post": { "summary": "Mark a storefront draft discard", "description": "Developer-scoped review status only. Does not apply content, publish a website or physically delete an asset. These IDs are not operational or product-setup draft IDs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [ { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "storefront_id": { "type": [ "integer", "string", "null" ] }, "tool_type": { "type": "string" }, "generated_payload_json": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "generated_asset_id": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js", "services/storefrontAiService.js" ] } }, "/api/developer/storefront/ai/navigation": { "post": { "summary": "Generate a storefront navigation draft", "description": "Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": [ "integer", "string", "null" ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [ "currentStorefront: object", "notes: string", "instructions: string", "mood: string", "visualMood: string", "tone: string", "targetCustomer: string", "bannerUse: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js", "services/storefrontAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentStorefront": { "type": "object", "properties": { "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden", "suspended" ] }, "displayName": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "bannerUrl": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "supportUrl": { "type": [ "string", "null" ] }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "themeMode": { "type": "string", "enum": [ "light", "dark", "system" ] }, "websiteTemplate": { "type": "string" }, "visualStyle": { "type": "string" }, "navMode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "mood": { "type": "string" }, "visualMood": { "type": "string" }, "tone": { "type": "string" }, "targetCustomer": { "type": "string" }, "bannerUse": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/storefront/ai/style": { "post": { "summary": "Generate a storefront style draft", "description": "Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": [ "integer", "string", "null" ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [ "currentStorefront: object", "notes: string", "instructions: string", "mood: string", "visualMood: string", "tone: string", "targetCustomer: string", "bannerUse: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js", "services/storefrontAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentStorefront": { "type": "object", "properties": { "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden", "suspended" ] }, "displayName": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "bannerUrl": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "supportUrl": { "type": [ "string", "null" ] }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "themeMode": { "type": "string", "enum": [ "light", "dark", "system" ] }, "websiteTemplate": { "type": "string" }, "visualStyle": { "type": "string" }, "navMode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "mood": { "type": "string" }, "visualMood": { "type": "string" }, "tone": { "type": "string" }, "targetCustomer": { "type": "string" }, "bannerUse": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/storefront/ai/template": { "post": { "summary": "Generate a storefront template draft", "description": "Uses enabled Google Gemini configuration, quotas, saved storefront/brand and up to 24 recent products. current_storefront and supported snake_case aliases are accepted. Banner generation can upload a draft public asset when storage is configured. Generation does not save/publish storefront settings. Inspect suggestions, draftId and persistenceWarning; a missing draft ID is not confirmed persistence.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": [ "integer", "string", "null" ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [ "currentStorefront: object", "notes: string", "instructions: string", "mood: string", "visualMood: string", "tone: string", "targetCustomer: string", "bannerUse: string", "aspectRatio: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js", "services/storefrontAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentStorefront": { "type": "object", "properties": { "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden", "suspended" ] }, "displayName": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "bannerUrl": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "supportUrl": { "type": [ "string", "null" ] }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "themeMode": { "type": "string", "enum": [ "light", "dark", "system" ] }, "websiteTemplate": { "type": "string" }, "visualStyle": { "type": "string" }, "navMode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "mood": { "type": "string" }, "visualMood": { "type": "string" }, "tone": { "type": "string" }, "targetCustomer": { "type": "string" }, "bannerUse": { "type": "string" }, "aspectRatio": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/storefront/hise-package": { "get": { "summary": "Generate the developer storefront WebView package", "description": "A separate store/account integration, not the product licensing package or a hosted/embedded web storefront installation.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/hise-packages" }, "parameters": [ { "name": "uiWidth", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "uiHeight", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "200 JSON { url, filename, expiresIn: 300 }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "expiresIn": { "const": 300 } }, "required": [ "url", "filename", "expiresIn" ], "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.manage and all-products workspace scope.", "x-request-fields": [ "query uiWidth: integer", "query uiHeight: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js" ] } }, "/api/developer/storefront/newsletter/readiness": { "get": { "summary": "Inspect newsletter confirmation transport", "description": "Configured transport is not proof of inbox delivery. Does not subscribe a customer or send a test.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: configured, status, message, sender.", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "status": { "type": "string" }, "message": { "type": "string" }, "sender": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js" ] } }, "/api/developer/storefront/newsletter/test": { "post": { "summary": "Send a confirmation-email test to the signed-in teammate", "description": "Actually sends email to the authenticated actor account, not an arbitrary body recipient. Limited to 3 requests per minute per signed-in user. Requires configured transport and a saved storefront. Does not create a newsletter subscription; provider acceptance is not guaranteed inbox placement.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: sent, recipient, message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" }, "recipient": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js" ] } }, "/api/developer/storefront/products": { "get": { "summary": "List permitted storefront product placements", "description": "Can initialize the developer storefront/default product placements. This read is not a zero-write health check. Returns placement rows with a nested product, not the public catalog product array.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: storefront, products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_user_id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "status": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "banner_url": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "accent_color": { "type": [ "string", "null" ] }, "theme_mode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "storefront_id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "visibility": { "type": "string" }, "sort_order": { "type": "integer" }, "product_slug": { "type": [ "string", "null" ] }, "custom_headline": { "type": [ "string", "null" ] }, "custom_description": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "is_draft": { "type": "boolean" }, "product_type": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view; results restricted to assigned products.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js" ] } }, "/api/developer/storefront/products/{productId}": { "patch": { "summary": "Save one owned product placement", "description": "Both methods use the same upsert normalization: omitted visibility defaults visible, sortOrder defaults 0, and omitted custom copy clears it. Read and send the intended full placement; PATCH does not preserve every omitted placement field. Does not publish the underlying product.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: setting, storefront, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "setting": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "storefront_id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "visibility": { "type": "string" }, "sort_order": { "type": "integer" }, "product_slug": { "type": [ "string", "null" ] }, "custom_headline": { "type": [ "string", "null" ] }, "custom_description": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "is_draft": { "type": "boolean" }, "product_type": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_user_id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "status": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "banner_url": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "accent_color": { "type": [ "string", "null" ] }, "theme_mode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and assigned-product access.", "x-request-fields": [ "visibility: visible | featured | unlisted | hidden", "sortOrder: integer", "productSlug: string", "customHeadline: string,null", "customDescription: string,null", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "visible", "featured", "unlisted", "hidden" ] }, "sortOrder": { "type": "integer" }, "productSlug": { "type": "string" }, "customHeadline": { "type": [ "string", "null" ] }, "customDescription": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } }, "put": { "summary": "Save one owned product placement", "description": "Both methods use the same upsert normalization: omitted visibility defaults visible, sortOrder defaults 0, and omitted custom copy clears it. Read and send the intended full placement; PATCH does not preserve every omitted placement field. Does not publish the underlying product.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: setting, storefront, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "setting": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "storefront_id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "visibility": { "type": "string" }, "sort_order": { "type": "integer" }, "product_slug": { "type": [ "string", "null" ] }, "custom_headline": { "type": [ "string", "null" ] }, "custom_description": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "is_draft": { "type": "boolean" }, "product_type": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_user_id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "status": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "banner_url": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "accent_color": { "type": [ "string", "null" ] }, "theme_mode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and assigned-product access.", "x-request-fields": [ "visibility: visible | featured | unlisted | hidden", "sortOrder: integer", "productSlug: string", "customHeadline: string,null", "customDescription: string,null", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "visible", "featured", "unlisted", "hidden" ] }, "sortOrder": { "type": "integer" }, "productSlug": { "type": "string" }, "customHeadline": { "type": [ "string", "null" ] }, "customDescription": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/developer/storefront/products/order": { "put": { "summary": "Save ordered product placements and optional homepage hero", "description": "items aliases products; product_id/id alias productId. Array position determines sort order; duplicate or foreign products fail. attached:false sets hidden. An explicit homepage hero must be a valid visible placement. Send the intended placement fields; this is not a generic sparse patch.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-management" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: storefront, products, count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developer_user_id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "status": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "banner_url": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "accent_color": { "type": [ "string", "null" ] }, "theme_mode": { "type": "string" }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pageTemplates": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "homepageMerchandising": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "templateContentSlots": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "storefront_id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "visibility": { "type": "string" }, "sort_order": { "type": "integer" }, "product_slug": { "type": [ "string", "null" ] }, "custom_headline": { "type": [ "string", "null" ] }, "custom_description": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "is_draft": { "type": "boolean" }, "product_type": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } }, "count": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "storefront.view, storefront.manage and all-products scope.", "x-request-fields": [ "products: array (required)", "homepageMerchandising: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerStorefrontRoutes.js", "services/storefrontService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "visibility": { "type": "string", "enum": [ "visible", "featured", "unlisted", "hidden" ] }, "attached": { "type": "boolean" } }, "additionalProperties": true }, "minItems": 1, "maxItems": 500 }, "homepageMerchandising": { "type": "object", "properties": { "heroProductId": { "type": [ "integer", "string", "null" ] } }, "additionalProperties": true } }, "required": [ "products" ], "additionalProperties": true } } } } } }, "/api/developer/storefront/readiness": { "get": { "summary": "Inspect the signed-in developer website readiness", "description": "Diagnostic output, not publication or checkout activation. Read blockers, warnings, categories, evidence and action links; a percentage alone is not approval. Developer checks include billing, settlement and email configuration and can initialize/read settlement or sender state. Do not use these as a zero-write uptime probe, a provider-verification certificate or a promise of live native-host runtime verification.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/readiness" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: scope, status, goLiveReady, completionPercent, developer_id, product_id, storefront_id, generated_at, blockers, warnings, categories, blockingCount, warningCount, requiredIncompleteCount, nextAction, nextActionCode, nextActionCategory, launchChecklist, categorySummary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "enum": [ "developer", "product", "storefront" ] }, "status": { "type": "string" }, "goLiveReady": { "type": "boolean" }, "completionPercent": { "type": "number" }, "developer_id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "storefront_id": { "type": [ "integer", "null" ] }, "generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "weight": { "type": "number" }, "completionPercent": { "type": "number" }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" }, "category": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "href": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "evidence": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "blockingCount": { "type": "integer" }, "warningCount": { "type": "integer" }, "requiredIncompleteCount": { "type": "integer" }, "nextAction": { "type": [ "string", "null" ] }, "nextActionCode": { "type": [ "string", "null" ] }, "nextActionCategory": { "type": [ "string", "null" ] }, "launchChecklist": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "categorySummary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account identity, not the selected effective workspace owner.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerReadinessRoutes.js", "services/developerReadinessService.js", "services/developerReadinessSummaryService.js" ] } }, "/api/developer/subscription-bundles": { "get": { "summary": "List bundle definitions in the effective developer workspace.", "description": "products.view and all-products scope. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Scoped bundle list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer" }, "failedPaymentGraceDays": { "type": "integer" }, "membershipMode": { "type": "string", "enum": [ "selected_products", "all_products" ] }, "fulfillmentMode": { "type": "string", "enum": [ "access", "keep_products" ] }, "basePriceStrategy": { "type": "string", "enum": [ "fixed", "percent_discount", "fixed_discount" ] }, "fixedBundlePriceCents": { "type": "integer", "minimum": 0 }, "discountValue": { "type": "number" }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "activeVersionId": { "type": "integer", "minimum": 1 }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account permissions and resource ownership described below.", "x-request-fields": [ "query status: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSubscriptionBundleRoutes.js", "services/subscriptionBundleService.js" ] }, "post": { "summary": "Create a bundle definition and version.", "description": "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. selected_products requires eligible productIds. fixed pricing requires fixedBundlePriceCents; discount strategies require discountValue. Prices remain subject to the paid minimum. Creating a new version does not bypass price notices or migrate existing billing authority. Side effects: Create a bundle definition and version. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [], "responses": { "201": { "description": "201: created bundle/version result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer" }, "failedPaymentGraceDays": { "type": "integer" }, "membershipMode": { "type": "string", "enum": [ "selected_products", "all_products" ] }, "fulfillmentMode": { "type": "string", "enum": [ "access", "keep_products" ] }, "basePriceStrategy": { "type": "string", "enum": [ "fixed", "percent_discount", "fixed_discount" ] }, "fixedBundlePriceCents": { "type": "integer", "minimum": 0 }, "discountValue": { "type": "number" }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "activeVersionId": { "type": "integer", "minimum": 1 }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account permissions and resource ownership described below.", "x-request-fields": [ "id: integer", "developerId: integer", "name: string (required)", "slug: string", "description: string,null", "status: string", "currency: string", "billingInterval: monthly | yearly", "trialDays: integer", "failedPaymentGraceDays: integer", "membershipMode: selected_products | all_products", "fulfillmentMode: access | keep_products", "basePriceStrategy: fixed | percent_discount | fixed_discount", "fixedBundlePriceCents: integer", "discountValue: number", "cancellationBehavior: access_until_period_end | lock_immediately", "environment: test | live", "activeVersionId: integer", "versions: array", "productIds: array", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "versionMetadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerSubscriptionBundleRoutes.js", "services/subscriptionBundleService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer" }, "failedPaymentGraceDays": { "type": "integer" }, "membershipMode": { "type": "string", "enum": [ "selected_products", "all_products" ] }, "fulfillmentMode": { "type": "string", "enum": [ "access", "keep_products" ] }, "basePriceStrategy": { "type": "string", "enum": [ "fixed", "percent_discount", "fixed_discount" ] }, "fixedBundlePriceCents": { "type": "integer", "minimum": 0 }, "discountValue": { "type": "number" }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "activeVersionId": { "type": "integer", "minimum": 1 }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "versionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "required": [ "name" ] } } } } } }, "/api/developer/subscription-bundles/{bundleId}": { "get": { "summary": "Read an owned bundle definition and versions.", "description": "products.view and all-products scope; another developer's definition is not exposed. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [ { "name": "bundleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ bundle }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer" }, "failedPaymentGraceDays": { "type": "integer" }, "membershipMode": { "type": "string", "enum": [ "selected_products", "all_products" ] }, "fulfillmentMode": { "type": "string", "enum": [ "access", "keep_products" ] }, "basePriceStrategy": { "type": "string", "enum": [ "fixed", "percent_discount", "fixed_discount" ] }, "fixedBundlePriceCents": { "type": "integer", "minimum": 0 }, "discountValue": { "type": "number" }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "activeVersionId": { "type": "integer", "minimum": 1 }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account permissions and resource ownership described below.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSubscriptionBundleRoutes.js", "services/subscriptionBundleService.js" ] }, "patch": { "summary": "Change bundle publication/status.", "description": "products.edit and all-products scope. Side effects: Change bundle publication/status. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [ { "name": "bundleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current bundle/status result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer" }, "failedPaymentGraceDays": { "type": "integer" }, "membershipMode": { "type": "string", "enum": [ "selected_products", "all_products" ] }, "fulfillmentMode": { "type": "string", "enum": [ "access", "keep_products" ] }, "basePriceStrategy": { "type": "string", "enum": [ "fixed", "percent_discount", "fixed_discount" ] }, "fixedBundlePriceCents": { "type": "integer", "minimum": 0 }, "discountValue": { "type": "number" }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "activeVersionId": { "type": "integer", "minimum": 1 }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account permissions and resource ownership described below.", "x-request-fields": [ "status: draft | published | archived (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerSubscriptionBundleRoutes.js", "services/subscriptionBundleService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "published", "archived" ] } }, "required": [ "status" ], "additionalProperties": true } } } } }, "put": { "summary": "Update an owned bundle through the versioned definition workflow.", "description": "products.edit and relevant product scope. Do not assume changing the catalog rewrites every prior paid-invoice ownership snapshot. Creates/updates the supported versioned plan. Customer history can lock the fulfillment model and environment. Product-managed plans must be edited from product setup. Changing monthly/yearly cadence with active, trialing, past_due or unpaid standalone or linked bundle contracts returns 409 SUBSCRIPTION_BILLING_INTERVAL_LOCKED. Keep existing contracts on their cadence and create a separate offer for the new interval. Side effects: Update an owned bundle through the versioned definition workflow. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [ { "name": "bundleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated bundle/version result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer" }, "failedPaymentGraceDays": { "type": "integer" }, "membershipMode": { "type": "string", "enum": [ "selected_products", "all_products" ] }, "fulfillmentMode": { "type": "string", "enum": [ "access", "keep_products" ] }, "basePriceStrategy": { "type": "string", "enum": [ "fixed", "percent_discount", "fixed_discount" ] }, "fixedBundlePriceCents": { "type": "integer", "minimum": 0 }, "discountValue": { "type": "number" }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "activeVersionId": { "type": "integer", "minimum": 1 }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account permissions and resource ownership described below.", "x-request-fields": [ "id: integer", "developerId: integer", "name: string (required)", "slug: string", "description: string,null", "status: string", "currency: string", "billingInterval: monthly | yearly", "trialDays: integer", "failedPaymentGraceDays: integer", "membershipMode: selected_products | all_products", "fulfillmentMode: access | keep_products", "basePriceStrategy: fixed | percent_discount | fixed_discount", "fixedBundlePriceCents: integer", "discountValue: number", "cancellationBehavior: access_until_period_end | lock_immediately", "environment: test | live", "activeVersionId: integer", "versions: array", "productIds: array", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "versionMetadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "SUBSCRIPTION_BILLING_INTERVAL_LOCKED" ], "x-source-files": [ "routes/developerSubscriptionBundleRoutes.js", "services/subscriptionBundleService.js", "services/subscriptionPlanSafetyService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer" }, "failedPaymentGraceDays": { "type": "integer" }, "membershipMode": { "type": "string", "enum": [ "selected_products", "all_products" ] }, "fulfillmentMode": { "type": "string", "enum": [ "access", "keep_products" ] }, "basePriceStrategy": { "type": "string", "enum": [ "fixed", "percent_discount", "fixed_discount" ] }, "fixedBundlePriceCents": { "type": "integer", "minimum": 0 }, "discountValue": { "type": "number" }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "activeVersionId": { "type": "integer", "minimum": 1 }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "versionMetadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "required": [ "name" ] } } } } } }, "/api/developer/subscription-bundles/reporting/summary": { "get": { "summary": "Read recurring bundle reporting totals.", "description": "products.view and all-products scope. Recurring amount is not a confirmed payout or proof every invoice was paid. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [], "responses": { "200": { "description": "{ summary } with active_subscriptions, recurring_amount_cents, past_due_subscriptions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "active_subscriptions": { "type": "integer" }, "recurring_amount_cents": { "type": "integer", "minimum": 0 }, "past_due_subscriptions": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account permissions and resource ownership described below.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSubscriptionBundleRoutes.js", "services/subscriptionBundleService.js" ] } }, "/api/developer/support": { "get": { "summary": "Read developer support content and routing", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/support" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: settings, articles, legacy, resolver, source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "businessAddress": { "type": "string" }, "supportPhone": { "type": "string" }, "primaryContactName": { "type": "string" }, "supportUrlOverride": { "type": "string" }, "supportUrlOverrideEnabled": { "type": "boolean" }, "supportDisplayName": { "type": "string" }, "supportContactLabel": { "type": "string" }, "responseTimeMessage": { "type": "string" }, "availabilityMessage": { "type": "string" }, "contactFormEnabled": { "type": "boolean" }, "contactFormDestinationEmail": { "type": "string" }, "aiAssistantEnabled": { "type": "boolean" }, "aiAssistantTone": { "type": "string" }, "escalationMessage": { "type": "string" }, "alwaysEscalateWhenUnsure": { "type": "boolean" }, "supportPageEnabled": { "type": "boolean" } }, "additionalProperties": true }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "productId": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "faq", "install", "activation", "download", "compatibility", "policy", "known_issue", "troubleshooting" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "sortOrder": { "type": "integer" }, "visible": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "legacy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "resolver": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "source": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.view and all-products workspace scope.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerSupportRoutes.js", "services/developerSupportService.js" ] }, "patch": { "summary": "Save support content and articles", "description": "These compatibility save handlers share the same service; PATCH is not a promise of generic JSON Patch semantics. Read the normalization rules and reload the saved result. Article content and contact routing do not change product entitlements.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/support" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: settings, articles, legacy, resolver, source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "businessAddress": { "type": "string" }, "supportPhone": { "type": "string" }, "primaryContactName": { "type": "string" }, "supportUrlOverride": { "type": "string" }, "supportUrlOverrideEnabled": { "type": "boolean" }, "supportDisplayName": { "type": "string" }, "supportContactLabel": { "type": "string" }, "responseTimeMessage": { "type": "string" }, "availabilityMessage": { "type": "string" }, "contactFormEnabled": { "type": "boolean" }, "contactFormDestinationEmail": { "type": "string" }, "aiAssistantEnabled": { "type": "boolean" }, "aiAssistantTone": { "type": "string" }, "escalationMessage": { "type": "string" }, "alwaysEscalateWhenUnsure": { "type": "boolean" }, "supportPageEnabled": { "type": "boolean" } }, "additionalProperties": true }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "productId": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "faq", "install", "activation", "download", "compatibility", "policy", "known_issue", "troubleshooting" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "sortOrder": { "type": "integer" }, "visible": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "legacy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "resolver": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "source": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.view plus settings.manage and all-products workspace scope. Only owner and administrator roles have settings.manage.", "x-request-fields": [ "supportEmail: string", "businessAddress: string", "supportPhone: string", "primaryContactName: string", "supportUrlOverride: string", "supportUrlOverrideEnabled: boolean", "supportDisplayName: string", "supportContactLabel: string", "responseTimeMessage: string", "availabilityMessage: string", "contactFormEnabled: boolean", "contactFormDestinationEmail: string", "aiAssistantEnabled: boolean", "aiAssistantTone: string", "escalationMessage: string", "alwaysEscalateWhenUnsure: boolean", "supportPageEnabled: boolean", "articles: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerSupportRoutes.js", "services/developerSupportService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "businessAddress": { "type": "string" }, "supportPhone": { "type": "string" }, "primaryContactName": { "type": "string" }, "supportUrlOverride": { "type": "string" }, "supportUrlOverrideEnabled": { "type": "boolean" }, "supportDisplayName": { "type": "string" }, "supportContactLabel": { "type": "string" }, "responseTimeMessage": { "type": "string" }, "availabilityMessage": { "type": "string" }, "contactFormEnabled": { "type": "boolean" }, "contactFormDestinationEmail": { "type": "string" }, "aiAssistantEnabled": { "type": "boolean" }, "aiAssistantTone": { "type": "string" }, "escalationMessage": { "type": "string" }, "alwaysEscalateWhenUnsure": { "type": "boolean" }, "supportPageEnabled": { "type": "boolean" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "productId": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "faq", "install", "activation", "download", "compatibility", "policy", "known_issue", "troubleshooting" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "sortOrder": { "type": "integer" }, "visible": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } } }, "put": { "summary": "Save support content and articles", "description": "These compatibility save handlers share the same service; PATCH is not a promise of generic JSON Patch semantics. Read the normalization rules and reload the saved result. Article content and contact routing do not change product entitlements.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/support" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: settings, articles, legacy, resolver, source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "businessAddress": { "type": "string" }, "supportPhone": { "type": "string" }, "primaryContactName": { "type": "string" }, "supportUrlOverride": { "type": "string" }, "supportUrlOverrideEnabled": { "type": "boolean" }, "supportDisplayName": { "type": "string" }, "supportContactLabel": { "type": "string" }, "responseTimeMessage": { "type": "string" }, "availabilityMessage": { "type": "string" }, "contactFormEnabled": { "type": "boolean" }, "contactFormDestinationEmail": { "type": "string" }, "aiAssistantEnabled": { "type": "boolean" }, "aiAssistantTone": { "type": "string" }, "escalationMessage": { "type": "string" }, "alwaysEscalateWhenUnsure": { "type": "boolean" }, "supportPageEnabled": { "type": "boolean" } }, "additionalProperties": true }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "productId": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "faq", "install", "activation", "download", "compatibility", "policy", "known_issue", "troubleshooting" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "sortOrder": { "type": "integer" }, "visible": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "legacy": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "resolver": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "source": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.view plus settings.manage and all-products workspace scope. Only owner and administrator roles have settings.manage.", "x-request-fields": [ "supportEmail: string", "businessAddress: string", "supportPhone: string", "primaryContactName: string", "supportUrlOverride: string", "supportUrlOverrideEnabled: boolean", "supportDisplayName: string", "supportContactLabel: string", "responseTimeMessage: string", "availabilityMessage: string", "contactFormEnabled: boolean", "contactFormDestinationEmail: string", "aiAssistantEnabled: boolean", "aiAssistantTone: string", "escalationMessage: string", "alwaysEscalateWhenUnsure: boolean", "supportPageEnabled: boolean", "articles: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerSupportRoutes.js", "services/developerSupportService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "businessAddress": { "type": "string" }, "supportPhone": { "type": "string" }, "primaryContactName": { "type": "string" }, "supportUrlOverride": { "type": "string" }, "supportUrlOverrideEnabled": { "type": "boolean" }, "supportDisplayName": { "type": "string" }, "supportContactLabel": { "type": "string" }, "responseTimeMessage": { "type": "string" }, "availabilityMessage": { "type": "string" }, "contactFormEnabled": { "type": "boolean" }, "contactFormDestinationEmail": { "type": "string" }, "aiAssistantEnabled": { "type": "boolean" }, "aiAssistantTone": { "type": "string" }, "escalationMessage": { "type": "string" }, "alwaysEscalateWhenUnsure": { "type": "boolean" }, "supportPageEnabled": { "type": "boolean" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "productId": { "type": [ "integer", "null" ] }, "type": { "type": "string", "enum": [ "faq", "install", "activation", "download", "compatibility", "policy", "known_issue", "troubleshooting" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "sortOrder": { "type": "integer" }, "visible": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } } } }, "/api/developer/support/ai/support-items": { "post": { "summary": "Generate draft FAQ and support content", "description": "Uses the product setup AI draft store, not operational drafts. Suggested faqs, supportNote, installSummary, troubleshooting and warnings must be reviewed and saved through the supported content workflow. Does not automatically publish articles, change refund terms or send a reply. Provider configuration and quotas still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/support" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ], "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion." }, { "type": "null" } ] }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "persistenceWarning": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "customers.view plus settings.manage and all-products scope.", "x-request-fields": [ "productId: integer", "currentProduct: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "notes: string", "instructions: string", "referenceUrl: string", "referenceUrls: array", "tone: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerSupportRoutes.js", "services/productSetupAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "currentProduct": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "referenceUrl": { "type": "string" }, "referenceUrls": { "type": "array", "items": { "type": "string" } }, "tone": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/developer/team": { "get": { "summary": "Workspace, current access, members, pending invitations, roles", "description": "Side effects: Reads authorized team information.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [], "responses": { "200": { "description": "Workspace, current access, members, pending invitations, roles", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "ownerUserId": { "type": "integer", "minimum": 1 }, "displayName": { "type": "string" } }, "additionalProperties": true }, "currentAccess": { "type": "object", "properties": { "workspaceId": { "type": "integer", "minimum": 1 }, "workspaceOwnerUserId": { "type": "integer", "minimum": 1 }, "workspaceDisplayName": { "type": "string" }, "membershipId": { "type": "integer", "minimum": 1 }, "userId": { "type": "integer", "minimum": 1 }, "effectiveDeveloperId": { "type": "integer", "minimum": 1 }, "isWorkspaceOwner": { "type": "boolean" }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "productScopeMode": { "type": "string" }, "allowedProductIds": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "userId": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string" }, "productScopeMode": { "type": "string", "enum": [ "all_products", "selected_products" ] }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true } }, "invitations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "productScopeMode": { "type": "string" }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true } }, "roles": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "team.view; workspace and product assignments are resolved server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ] } }, "/api/developer/team/audit": { "get": { "summary": "Returns team audit events without sensitive tokens", "description": "Side effects: Reads authorized team information.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "description": "" } ], "responses": { "200": { "description": "200 { audit: [...] }. Treat email addresses and audit identities as private data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "action": { "type": "string" }, "actor_user_id": { "type": "integer", "minimum": 1 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "team.audit.view; workspace and product assignments are resolved server-side.", "x-request-fields": [ "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ] } }, "/api/developer/team/invitations": { "get": { "summary": "Pending invitations only", "description": "Side effects: Reads authorized team information.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [], "responses": { "200": { "description": "Pending invitations only", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "productScopeMode": { "type": "string" }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true } }, "workspace": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "ownerUserId": { "type": "integer", "minimum": 1 }, "displayName": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "team.view; workspace and product assignments are resolved server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ] }, "post": { "summary": "Creates one-time expiring email invitation; stores token hash only", "description": "selected_products requires at least one owned product ID. Creation defaults to all_products. The raw token is emailed, not returned. The invitation expires after seven days; inspect the separate email outcome. Side effects: Changes team membership or invitation state and records audit activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [], "responses": { "201": { "description": "201 { invitation, email }. The raw token is sent by transactional email, not returned in this JSON. Inspect the email outcome separately.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitation": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "productScopeMode": { "type": "string" }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true }, "email": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "team.invite; workspace and product assignments are resolved server-side.", "x-request-fields": [ "email: string (required)", "role: administrator | product_manager | customer_support | marketing | analyst | billing | engineer (required)", "productScopeMode: all_products | selected_products", "selectedProductIds: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "administrator", "product_manager", "customer_support", "marketing", "analyst", "billing", "engineer" ] }, "productScopeMode": { "type": "string", "enum": [ "all_products", "selected_products" ] }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "required": [ "email", "role" ], "additionalProperties": true } } } } } }, "/api/developer/team/invitations/{invitationId}": { "delete": { "summary": "Revokes pending invitation", "description": "Side effects: Changes team membership or invitation state and records audit activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 { invitation, revoked: true }. A missing or no-longer-pending invitation returns 404.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitation": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "productScopeMode": { "type": "string" }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true }, "revoked": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "team.invite; workspace and product assignments are resolved server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ] } }, "/api/developer/team/invitations/accept": { "post": { "summary": "Accepts one-time token and creates membership", "description": "Sign in with the invited email. Used, expired, revoked and superseded invitations cannot grant access. Side effects: Changes team membership or invitation state and records audit activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [], "responses": { "200": { "description": "200 { member, workspaceAccess }. Acceptance creates membership; repeated acceptance is rejected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "userId": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string" }, "productScopeMode": { "type": "string", "enum": [ "all_products", "selected_products" ] }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true }, "workspaceAccess": { "type": "object", "properties": { "workspaceId": { "type": "integer", "minimum": 1 }, "workspaceOwnerUserId": { "type": "integer", "minimum": 1 }, "workspaceDisplayName": { "type": "string" }, "membershipId": { "type": "integer", "minimum": 1 }, "userId": { "type": "integer", "minimum": 1 }, "effectiveDeveloperId": { "type": "integer", "minimum": 1 }, "isWorkspaceOwner": { "type": "boolean" }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "productScopeMode": { "type": "string" }, "allowedProductIds": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "authenticated invited email; workspace and product assignments are resolved server-side.", "x-request-fields": [ "token: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": true } } } } } }, "/api/developer/team/members": { "get": { "summary": "Team members only", "description": "Side effects: Reads authorized team information.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [], "responses": { "200": { "description": "Team members only", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "userId": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string" }, "productScopeMode": { "type": "string", "enum": [ "all_products", "selected_products" ] }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true } }, "workspace": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "ownerUserId": { "type": "integer", "minimum": 1 }, "displayName": { "type": "string" } }, "additionalProperties": true }, "currentAccess": { "type": "object", "properties": { "workspaceId": { "type": "integer", "minimum": 1 }, "workspaceOwnerUserId": { "type": "integer", "minimum": 1 }, "workspaceDisplayName": { "type": "string" }, "membershipId": { "type": "integer", "minimum": 1 }, "userId": { "type": "integer", "minimum": 1 }, "effectiveDeveloperId": { "type": "integer", "minimum": 1 }, "isWorkspaceOwner": { "type": "boolean" }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "productScopeMode": { "type": "string" }, "allowedProductIds": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "team.view; workspace and product assignments are resolved server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ] } }, "/api/developer/team/members/{memberId}": { "delete": { "summary": "Revokes membership without deleting the user account", "description": "Removes membership, not the user account; saved sessions are revoked. Side effects: Changes team membership or invitation state and records audit activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 { member, removed: true }. Removes workspace access, not the user account; sessions are revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "userId": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string" }, "productScopeMode": { "type": "string", "enum": [ "all_products", "selected_products" ] }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true }, "removed": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "team.remove; workspace and product assignments are resolved server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ] }, "patch": { "summary": "Changes role and product scope with owner/last-owner protections", "description": "Send the complete selectedProductIds array for an existing selected_products member, including a role-only update. Owner assignment is owner-only; self-modification and removing the last active owner are prohibited. Existing sessions are revoked. Side effects: Changes team membership or invitation state and records audit activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 { member, updated: true }. Existing sessions are revoked; the member may need to sign in again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "userId": { "type": "integer", "minimum": 1 }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "status": { "type": "string" }, "productScopeMode": { "type": "string", "enum": [ "all_products", "selected_products" ] }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true }, "updated": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "team.manage_roles; workspace and product assignments are resolved server-side.", "x-request-fields": [ "role: owner | administrator | product_manager | customer_support | marketing | analyst | billing | engineer", "productScopeMode: all_products | selected_products", "selectedProductIds: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "administrator", "product_manager", "customer_support", "marketing", "analyst", "billing", "engineer" ] }, "productScopeMode": { "type": "string", "enum": [ "all_products", "selected_products" ] }, "selectedProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, "additionalProperties": true } } } } } }, "/api/developer/team/roles": { "get": { "summary": "Returns canonical role and permission registry", "description": "Side effects: Reads authorized team information.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/team-accounts" }, "parameters": [], "responses": { "200": { "description": "200 { roles, permissions, productScopeModes, sensitivePermissions }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "permissions": { "type": "array", "items": { "type": "string" } }, "productScopeModes": { "type": "array", "items": { "type": "string" } }, "sensitivePermissions": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "authenticated developer; workspace and product assignments are resolved server-side.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerTeamRoutes.js", "services/developerTeamService.js", "services/developerTeamPermissions.js" ] } }, "/api/developer/webhook": { "get": { "summary": "List or create developer webhook endpoints from the developer console.", "description": "Developer webhook permissions and all-products scope apply. Missing storage can return DEVELOPER_WEBHOOKS_UNAVAILABLE for mutations.", "externalDocs": { "url": "https://www.soundsync.dev/docs/webhooks" }, "parameters": [], "responses": { "200": { "description": "Webhook list or created webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "501": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/devWebhookRoutes.js", "controllers/devWebhookController.js" ] }, "post": { "summary": "List or create developer webhook endpoints from the developer console.", "description": "Stores a developer outbound webhook and returns its signing secret privately. This endpoint reads url, not an arbitrary event list.", "externalDocs": { "url": "https://www.soundsync.dev/docs/webhooks" }, "parameters": [], "responses": { "201": { "description": "Webhook list or created webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "secret": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "501": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "url: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/devWebhookRoutes.js", "controllers/devWebhookController.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ], "additionalProperties": true } } } } } }, "/api/developer/webhook/{id}": { "delete": { "summary": "Delete a developer webhook endpoint.", "description": "Developer webhook permissions and all-products scope apply. Missing storage can return DEVELOPER_WEBHOOKS_UNAVAILABLE for mutations.", "externalDocs": { "url": "https://www.soundsync.dev/docs/webhooks" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deletion result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "501": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/devWebhookRoutes.js", "controllers/devWebhookController.js" ] } }, "/api/developer/webhook/{id}/secret": { "get": { "summary": "Return the signing secret for a developer webhook.", "description": "Private webhook signing material. Never embed it in a plugin, public page, screenshot or shared log.", "externalDocs": { "url": "https://www.soundsync.dev/docs/webhooks" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook signing secret for the selected endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "secret": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "501": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/devWebhookRoutes.js", "controllers/devWebhookController.js" ] } }, "/api/developer/webhook/{id}/test": { "post": { "summary": "Send a developer webhook test event.", "description": "Sends the server-defined synthetic purchase.completed test to the saved destination. No custom request-body test event is read; this makes a real outbound HTTP request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/webhooks" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook test result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "integer" }, "responsePreview": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "501": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/devWebhookRoutes.js", "controllers/devWebhookController.js" ] } }, "/api/download/proxy": { "get": { "summary": "Authorize a legacy protected file download and redirect to signed R2 delivery.", "description": "Requires both the legacy token query parameter and the signed-in customer who owns its serial. file must identify an authorized managed product file. This call records download activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/delivery-downloads" }, "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" }, { "name": "file", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" } ], "responses": { "302": { "description": "Authorized redirect to short-lived signed R2 delivery.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Short-lived authorized private download URL." } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT + private token query parameter", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query token: string (required)", "query file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [], "LegacyDownloadQueryToken": [] } ], "x-contract-coverage": "Reviewed transport contract; inspect the redirect/response headers and operation-specific authorization.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/downloadRoutes.js", "controllers/downloadController.js" ] } }, "/api/download/wrapped": { "get": { "summary": "Authorize a legacy indexed file download and redirect managed files to signed R2 delivery.", "description": "Requires legacy serial-token context and signed-in customer ownership. i is a zero-based file index. Unmanaged external files require import rather than an arbitrary proxy redirect.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/delivery-downloads" }, "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" }, { "name": "i", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "required": true, "description": "" } ], "responses": { "302": { "description": "Authorized redirect to short-lived signed R2 delivery, or an import-required error for unmanaged external assets.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Short-lived authorized private download URL." } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT + private token query parameter", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query token: string (required)", "query i: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [], "LegacyDownloadQueryToken": [] } ], "x-contract-coverage": "Reviewed transport contract; inspect the redirect/response headers and operation-specific authorization.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/downloadRoutes.js", "controllers/downloadController.js" ] } }, "/api/embed/storefront/{storeSlug}/bootstrap": { "get": { "summary": "Fetch the embedded storefront bootstrap payload.", "description": "Unauthorized embed domains return EMBED_DOMAIN_NOT_ALLOWED. Allowed embed origin/domain checks apply. The origin policy is not replaced by a developer JWT. Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-embed" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "product", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Storefront, pages, products, bundles, active page, reviews/support when requested, and embed metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1, "description": "Review IDs can be serialized strings; preserve the value when using moderation routes." }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "productSlug": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "imported": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "supportArticles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "type": { "type": "string" }, "visible": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "additionalProperties": true } }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "siteStructureRevision": { "type": "integer" }, "siteStructureUpdatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "navigation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "embed": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "domain": { "type": [ "string", "null" ] }, "parentOrigin": { "type": "string" }, "instanceId": { "type": "string" }, "scriptUrl": { "type": "string" } }, "additionalProperties": true }, "pages": { "type": "array", "items": { "type": "object", "properties": { "pageType": { "type": "string" }, "pageSlug": { "type": "string" }, "templateKey": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } }, "store": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "brand": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "page": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "bundles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "currency": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trialDays": { "type": "integer" }, "failedPaymentGraceDays": { "type": "integer" }, "membershipMode": { "type": "string", "enum": [ "selected_products", "all_products" ] }, "fulfillmentMode": { "type": "string", "enum": [ "access", "keep_products" ] }, "basePriceStrategy": { "type": "string", "enum": [ "fixed", "percent_discount", "fixed_discount" ] }, "fixedBundlePriceCents": { "type": "integer", "minimum": 0 }, "discountValue": { "type": "number" }, "cancellationBehavior": { "type": "string", "enum": [ "access_until_period_end", "lock_immediately" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "activeVersionId": { "type": "integer", "minimum": 1 }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Store slug, allowed parent origin, page, and product scope.", "x-request-fields": [ "query page: string", "query product: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/bundles": { "get": { "summary": "List active bundle offers and published subscription plans", "description": "Origin denial can record an installation-check event.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, bundles.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "slug": { "type": "string" } }, "additionalProperties": true }, "bundles": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "offerType": { "type": "string" }, "status": { "type": "string" }, "discountType": { "type": "string" }, "discountValue": { "type": "number" }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checkoutBacked": { "type": "boolean" }, "recurringAmountCents": { "type": "integer" }, "currency": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/bundles/{bundleSlug}": { "get": { "summary": "Read an active storefront bundle", "description": "Origin denial can record an installation-check event.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bundleSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, bundle.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "slug": { "type": "string" } }, "additionalProperties": true }, "bundle": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "offerType": { "type": "string" }, "status": { "type": "string" }, "discountType": { "type": "string" }, "discountValue": { "type": "number" }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checkoutBacked": { "type": "boolean" }, "recurringAmountCents": { "type": "integer" }, "currency": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/bundles/{bundleSlug}/price-check": { "post": { "summary": "Preview bundle ownership pricing", "description": "Origin denial can record an installation-check event. Optional Bearer library token is resolved by the server; invalid/expired tokens are treated as unauthenticated. Prefer the header, not URL query tokens. This is a price/ownership preview, not a charge or new entitlement. Checkout recalculates final eligibility/pricing. Subscription plans return recurring price with no existing-owner discount.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bundleSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: bundle, customerAuthenticated, fullPriceCents, ownedValueCents, missingSubtotalCents, eligibleDiscountCents, upgradePriceCents, finalCheckoutTotalCents, currency, ownedItems, missingItems, checkout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "offerType": { "type": "string" }, "status": { "type": "string" }, "discountType": { "type": "string" }, "discountValue": { "type": "number" }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checkoutBacked": { "type": "boolean" }, "recurringAmountCents": { "type": "integer" }, "currency": { "type": "string" } }, "additionalProperties": true }, "customerAuthenticated": { "type": "boolean" }, "fullPriceCents": { "type": "integer" }, "ownedValueCents": { "type": "integer" }, "missingSubtotalCents": { "type": "integer" }, "eligibleDiscountCents": { "type": "integer" }, "upgradePriceCents": { "type": "integer" }, "finalCheckoutTotalCents": { "type": "integer" }, "currency": { "type": "string" }, "ownedItems": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "missingItems": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checkout": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Optional authentication OR Customer library/download token", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ {}, { "LibraryToken": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/cart": { "post": { "summary": "Accept client-side cart state for embedded storefront display.", "description": "An echo for client cart display, not a priced or authorized server cart. Use /api/checkout/product for current checkout creation.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/checkout-cart" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted cart echo plus checkout endpoint. Checkout recalculates server-side.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cart": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "serverCalculated": { "const": false } }, "additionalProperties": true }, "checkoutEndpoint": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "items: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } }, "additionalProperties": true } } } } } }, "/api/embed/storefront/{storeSlug}/cart/coupon": { "post": { "summary": "Attach a coupon/promo code to embedded cart display.", "description": "Echoes code or coupon only. Final validation occurs during checkout; a successful echo is not a valid discount.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/checkout-cart" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Coupon echo. Final validation happens during server-side checkout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "coupon": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "code: string", "coupon: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "coupon": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/embed/storefront/{storeSlug}/cart/items": { "post": { "summary": "Accept one embedded cart item for display.", "description": "Echoes the body for display; does not reserve inventory, validate totals or start payment.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/checkout-cart" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted item echo plus checkout endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "checkoutEndpoint": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "productId: integer", "quantity: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } } } }, "/api/embed/storefront/{storeSlug}/catalog": { "get": { "summary": "List products for an embedded storefront.", "description": "Allowed embed origin/domain checks apply. The origin policy is not replaced by a developer JWT.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Embedded catalog product payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/checkout": { "post": { "summary": "Compatibility endpoint for embedded storefront checkout attempts.", "description": "Embedded storefront checkout is intentionally handed off to canonical product checkout. Compatibility endpoint; does not create checkout. Send authenticated checkout requests to /api/checkout/product. Side effects: None; returns a compatibility response pointing to canonical product checkout.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/checkout" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "409 USE_PRODUCT_CHECKOUT_ENDPOINT and checkoutEndpoint /api/checkout/product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "const": "USE_PRODUCT_CHECKOUT_ENDPOINT" }, "message": { "type": "string" }, "checkoutEndpoint": { "const": "/api/checkout/product" } }, "additionalProperties": true } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Use the authentication and resource scope specified for this operation.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/config": { "get": { "summary": "Load embed storefront configuration after allowed-domain check.", "description": "Allowed embed origin/domain checks apply. The origin policy is not replaced by a developer JWT.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Storefront payload, pages, navigation, site structure, and embed metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1, "description": "Review IDs can be serialized strings; preserve the value when using moderation routes." }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "productSlug": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "imported": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "supportArticles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "type": { "type": "string" }, "visible": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "additionalProperties": true } }, "siteStructure": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "siteStructureRevision": { "type": "integer" }, "siteStructureUpdatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "navigation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "embed": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "domain": { "type": [ "string", "null" ] }, "parentOrigin": { "type": "string" }, "instanceId": { "type": "string" }, "scriptUrl": { "type": "string" } }, "additionalProperties": true }, "pages": { "type": "array", "items": { "type": "object", "properties": { "pageType": { "type": "string" }, "pageSlug": { "type": "string" }, "templateKey": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/customer/library": { "get": { "summary": "Load embedded customer library.", "description": "When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer library payload for owned products, downloads, serials, subscriptions, and support.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "profile": { "type": "object", "properties": {}, "additionalProperties": true }, "prefs": { "type": "object", "properties": {}, "additionalProperties": true }, "download_token": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Customer library/download token", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "Authorization bearer token or token/download_token/libraryToken query parameter." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "LibraryToken": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "SESSION_VERIFICATION_UNAVAILABLE", "LIBRARY_SESSION_REVOKED" ], "x-source-files": [ "routes/embedStorefrontRoutes.js", "controllers/libraryController.js", "services/customerLibraryIdentityService.js" ] } }, "/api/embed/storefront/{storeSlug}/customer/ownership": { "get": { "summary": "Preview bundle ownership for a customer", "description": "Origin denial can record an installation-check event. Optional Bearer library token is resolved by the server; invalid/expired tokens are treated as unauthenticated. Prefer the header, not URL query tokens. This is a price/ownership preview, not a charge or new entitlement. Checkout recalculates final eligibility/pricing. Subscription plans return recurring price with no existing-owner discount. Without a bundle slug, customerAuthenticated only indicates token presence, not validated identity; ownedItems/missingItems are empty. Never grant access based on that presence flag.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bundle", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "bundleSlug", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "bundle_slug", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: review the response schema below.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "offerType": { "type": "string" }, "status": { "type": "string" }, "discountType": { "type": "string" }, "discountValue": { "type": "number" }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checkoutBacked": { "type": "boolean" }, "recurringAmountCents": { "type": "integer" }, "currency": { "type": "string" } }, "additionalProperties": true }, "customerAuthenticated": { "type": "boolean" }, "fullPriceCents": { "type": "integer" }, "ownedValueCents": { "type": "integer" }, "missingSubtotalCents": { "type": "integer" }, "eligibleDiscountCents": { "type": "integer" }, "upgradePriceCents": { "type": "integer" }, "finalCheckoutTotalCents": { "type": "integer" }, "currency": { "type": "string" }, "ownedItems": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "missingItems": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checkout": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, { "type": "object", "properties": { "customerAuthenticated": { "type": "boolean" }, "ownedItems": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "missingItems": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "message": { "type": "string" } }, "additionalProperties": true } ] } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Optional authentication OR Customer library/download token", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [ "query bundle: string", "query bundleSlug: string", "query bundle_slug: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ {}, { "LibraryToken": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/frame-config": { "get": { "summary": "Validate a frame token and return iframe protocol metadata.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-embed" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ok, storeSlug, parentOrigin, instanceId, mode, protocol soundsync-storefront-embed, version 1.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "storeSlug": { "type": "string" }, "parentOrigin": { "type": "string" }, "instanceId": { "type": "string" }, "mode": { "type": "string" }, "protocol": { "const": "soundsync-storefront-embed" }, "version": { "const": 1 }, "siteStructureRevision": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "FrameToken", "x-access-scope": "Store slug, parent origin, instance, frame route.", "x-request-fields": [ "frameToken/frame_token query", "parentOrigin/headers" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "FrameToken": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/embedStorefrontRoutes.js" ] } }, "/api/embed/storefront/{storeSlug}/frame-token": { "post": { "summary": "Issue a short-lived frame token for iframe storefront package loading.", "description": "The parent origin must be permitted for this store. The token is private, short-lived and bound to the frame instance; it is not an account session. Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-embed" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "frameToken, expiresInSeconds 600, frameUrl, embed metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "frameToken": { "type": "string" }, "expiresInSeconds": { "const": 600 }, "frameUrl": { "type": "string" }, "embed": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "domain": { "type": [ "string", "null" ] }, "parentOrigin": { "type": "string" }, "instanceId": { "type": "string" }, "scriptUrl": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Store slug, parent origin, instance id, frame route, storefront mode.", "x-request-fields": [ "parentOrigin: string (required)", "instanceId: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parentOrigin": { "type": "string" }, "instanceId": { "type": "string" } }, "required": [ "parentOrigin", "instanceId" ], "additionalProperties": true } } } } } }, "/api/embed/storefront/{storeSlug}/pages": { "get": { "summary": "List published pages and generated system defaults", "description": "Origin denial can record an installation-check event. Explicit unpublished stored pages remain hidden; a generated default does not bypass an explicit unpublished page.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, pages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "pages": { "type": "array", "items": { "type": "object", "properties": { "pageType": { "type": "string" }, "pageSlug": { "type": "string" }, "templateKey": { "type": "string" }, "status": { "type": "string" }, "selectedTemplate": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "availableTemplates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "publishingTargets": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/pages/{pageType}": { "get": { "summary": "Read one published page definition", "description": "Origin denial can record an installation-check event. Unsupported page types return 400; explicitly unpublished pages return 404. Page definitions are structured data, not arbitrary website HTML.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pageType", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "page": { "type": "object", "properties": { "pageType": { "type": "string" }, "pageSlug": { "type": "string" }, "templateKey": { "type": "string" }, "status": { "type": "string" }, "selectedTemplate": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "availableTemplates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "publishingTargets": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/products/{productSlug}": { "get": { "summary": "Read public product detail and reviews", "description": "Origin denial can record an installation-check event.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, product, reviews.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/reviews": { "get": { "summary": "Read published storefront reviews", "description": "Origin denial can record an installation-check event. page selects the paginated reviews workflow; without page, summary describes the returned limited review set. This embed handler does not resolve a token into eligibleProducts. Use the authenticated review/account flow for posting; public reviews are not proof of every purchaser being verified.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "rating", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: storefront, reviews, summary, eligibleProducts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "summary": { "type": "object", "properties": { "count": { "type": "integer" }, "averageRating": { "type": "number" } }, "additionalProperties": true }, "eligibleProducts": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [ "query limit: integer", "query page: integer", "query search: string", "query rating: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/support": { "get": { "summary": "Read published storefront support content", "description": "Origin denial can record an installation-check event.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, support, articles, aiAssistant, contactForm.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "support": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "articles": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "aiAssistant": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "contactForm": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/templates": { "get": { "summary": "Read page template selections and registry", "description": "Origin denial can record an installation-check event.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, registry, pages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "registry": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "pages": { "type": "array", "items": { "type": "object", "properties": { "pageType": { "type": "string" }, "pageSlug": { "type": "string" }, "templateKey": { "type": "string" }, "status": { "type": "string" }, "selectedTemplate": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "availableTemplates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "publishingTargets": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/templates/{pageType}": { "get": { "summary": "Read one page template selection", "description": "Origin denial can record an installation-check event.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pageType", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, pageType, pageSlug, templateKey, status, selectedTemplate, availableTemplates, publishingTargets, content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "pageType": { "type": "string" }, "pageSlug": { "type": "string" }, "templateKey": { "type": "string" }, "status": { "type": "string" }, "selectedTemplate": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "availableTemplates": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "publishingTargets": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Published storefront and allowed embed origin; origin checks are not customer authentication.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/embed/storefront/{storeSlug}/test-install": { "post": { "summary": "Record and test an embedded storefront installation.", "description": "Records/tests installation context under allowed-origin policy. page_id aliases pageId; detected defaults to true. It is not an uptime test or customer authentication.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "storeSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detected/allowed/domain/status result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recorded": { "type": "boolean" }, "allowed": { "type": "boolean" }, "domain": { "type": "string" }, "reason": { "type": "string" }, "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Allowed embed origin/domain; see the frame and operation notes", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "origin: string", "host: string", "domain: string", "pageId: integer", "detected: boolean", "referrer: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/embedStorefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "origin": { "type": "string" }, "host": { "type": "string" }, "domain": { "type": "string" }, "pageId": { "type": "integer", "minimum": 1 }, "detected": { "type": "boolean" }, "referrer": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/library": { "get": { "summary": "Return customer portal/library payload for a library token.", "description": "When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks. Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-library" }, "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "download_token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "libraryToken", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Products, subscriptions, licenses/serials, orders, marketing preferences, account profile, support, and download_token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "licenses": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "orders": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "prefs": { "type": "object", "properties": {}, "additionalProperties": true }, "profile": { "type": "object", "properties": {}, "additionalProperties": true }, "support": { "type": "object", "properties": {}, "additionalProperties": true }, "download_token": { "type": "string" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Customer library/download token", "x-access-scope": "Customer identity plus optional storefront/developer scope.", "x-request-fields": [ "query token: string", "query download_token: string", "query libraryToken: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "LibraryToken": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "SESSION_VERIFICATION_UNAVAILABLE", "LIBRARY_SESSION_REVOKED" ], "x-source-files": [ "controllers/libraryController.js", "services/customerLibraryIdentityService.js" ] } }, "/api/library/claim": { "post": { "summary": "Claim an external reseller/partner order item into the authenticated customer/developer account.", "description": "Requires an account JWT and a supported private claim token. claim is also accepted as a query alias. It does not create payment authority. Side effects: Claims an external reseller order item when the claim token is valid.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-library" }, "parameters": [], "responses": { "200": { "description": "Claim result or LIBRARY_CLAIM_FAILED error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "claimed": { "type": "boolean" }, "redirect_to": { "type": "string" }, "customer_id": { "type": "integer", "minimum": 1 }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true }, "order": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "external_order_id": { "type": "string" } }, "additionalProperties": true }, "license": { "type": "object", "properties": { "serial": { "type": [ "string", "null" ] }, "entitlement_id": { "type": [ "integer", "null" ] }, "status": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "claim: string", "claim_token: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/libraryRoutes.js", "controllers/libraryController.js", "services/customerActivationResetService.js", "services/licenseActivationService.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "claim": { "type": "string" }, "claim_token": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/library/expansions": { "get": { "summary": "List expansion library entries.", "description": "When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/delivery-downloads" }, "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "storefront", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Expansion library payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ownedBaseProducts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "ownedExpansions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "availableExpansions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "lockedExpansions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "download_token": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Customer library/download token", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query token: string", "query storefront: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "LibraryToken": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "SESSION_VERIFICATION_UNAVAILABLE", "LIBRARY_SESSION_REVOKED" ], "x-source-files": [ "routes/libraryRoutes.js", "controllers/libraryController.js", "services/customerActivationResetService.js", "services/licenseActivationService.js", "services/partnerHubService.js", "services/customerLibraryIdentityService.js" ] } }, "/api/library/licenses/{kind}/{licenseId}/reset-activations": { "post": { "summary": "Reset the current customer's eligible device activations", "description": "kind is serial or entitlement. Account Bearer token only, not a shared library/download link. Send null before the first reset or the exact last value read. Enablement, cooldown, current active devices and stale-state conflicts are checked. When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-library" }, "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "licenseId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "storefront", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Updated reset result or an eligibility/conflict error; reload before another action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reset": { "type": "boolean" }, "resetCount": { "type": "integer" }, "serialCount": { "type": "integer" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "License ownership, developer reset enablement, cooldown, and storefront scope are checked.", "x-request-fields": [ "query storefront: string", "expectedLastResetAt: string,null (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "SESSION_VERIFICATION_UNAVAILABLE", "LIBRARY_SESSION_REVOKED" ], "x-source-files": [ "routes/libraryRoutes.js", "controllers/libraryController.js", "services/customerActivationResetService.js", "services/licenseActivationService.js", "services/partnerHubService.js", "services/customerLibraryIdentityService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedLastResetAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "expectedLastResetAt" ], "additionalProperties": true } } } } } }, "/api/library/orders/{orderId}/invoice.pdf": { "get": { "summary": "Customer-authorized order invoice", "description": "Requires customer account identity, not a shared download token. Only owned orders are returned; invoice generation unavailability is an error. When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: application/pdf.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "SESSION_VERIFICATION_UNAVAILABLE", "LIBRARY_SESSION_REVOKED" ], "x-source-files": [ "routes/libraryRoutes.js", "controllers/libraryController.js", "services/customerActivationResetService.js", "services/licenseActivationService.js", "services/partnerHubService.js", "services/customerLibraryIdentityService.js" ] } }, "/api/library/products/{productId}/expansions": { "get": { "summary": "List expansions for a product.", "description": "When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/delivery-downloads" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "storefront", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Product expansion payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "parent": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "expansions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "download_token": { "type": "string" }, "source": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Customer library/download token", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query token: string", "query storefront: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "LibraryToken": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "SESSION_VERIFICATION_UNAVAILABLE", "LIBRARY_SESSION_REVOKED" ], "x-source-files": [ "routes/libraryRoutes.js", "controllers/libraryController.js", "services/customerActivationResetService.js", "services/licenseActivationService.js", "services/partnerHubService.js", "services/customerLibraryIdentityService.js" ] } }, "/api/library/products/{productId}/reviews": { "get": { "summary": "List or submit product reviews from library context.", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/delivery-downloads" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Review list or created review state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "imported": { "type": "boolean" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "customerName": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "summary": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "averageRating": { "type": "number", "minimum": 0, "maximum": 5 } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "Review payload for POST." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "controllers/libraryController.js", "services/productReviewService.js" ] }, "post": { "summary": "List or submit product reviews from library context.", "description": "When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/delivery-downloads" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Review list or created review state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "imported": { "type": "boolean" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "customerName": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "moderation": { "type": "object", "properties": { "status": { "type": "string" }, "awaitingApproval": { "type": "boolean" }, "message": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "rating: integer (required)", "title: string", "body: string", "review: string", "feedback: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "SESSION_VERIFICATION_UNAVAILABLE", "LIBRARY_SESSION_REVOKED" ], "x-source-files": [ "controllers/libraryController.js", "services/productReviewService.js", "services/customerLibraryIdentityService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string", "maxLength": 140 }, "body": { "type": "string", "minLength": 1, "maxLength": 5000 }, "review": { "type": "string" }, "feedback": { "type": "string" } }, "required": [ "rating" ], "additionalProperties": true, "anyOf": [ { "required": [ "body" ] }, { "required": [ "review" ] }, { "required": [ "feedback" ] } ] } } } } } }, "/api/library/redeem-serial": { "post": { "summary": "Customer serial claim; ownership proof still applies", "description": "Send one supported serial alias. Account ownership, redeemed/revoked state and current product access are checked. Repeated owned access can return created:false.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: message, product, serial, entitlement, created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "serial": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 } }, "additionalProperties": true }, "entitlement": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "state": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 } }, "additionalProperties": true }, "created": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "serial: string", "serialCode: string", "serial_code: string", "code: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/libraryRoutes.js", "controllers/libraryController.js", "services/customerActivationResetService.js", "services/licenseActivationService.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "serial": { "type": "string" }, "serialCode": { "type": "string" }, "serial_code": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/license/branding": { "get": { "summary": "Product-scoped branding; no serial is required for the branding lookup", "description": "Returns supported product/developer branding under product authentication. Branding is not proof of customer ownership or audio authorization.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-library" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: ok, branding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "branding": { "type": [ "object", "null" ], "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js" ] }, "post": { "summary": "Product-scoped branding; no serial is required for the branding lookup", "description": "Returns supported product/developer branding under product authentication. Branding is not proof of customer ownership or audio authorization.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/branding-library" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: ok, branding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "branding": { "type": [ "object", "null" ], "properties": { "storeName": { "type": "string" }, "developerDisplayName": { "type": "string" }, "tagline": { "type": "string" }, "slug": { "type": "string" }, "shortDescription": { "type": "string" }, "marketplaceBio": { "type": "string" }, "logos": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "iconUrl": { "type": "string" }, "defaultProductImageUrl": { "type": "string" } }, "additionalProperties": true }, "colors": { "type": "object", "properties": { "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "backgroundColor": { "type": "string" }, "brandHighlightColor": { "type": "string" }, "accentColor": { "type": "string" }, "advancedOverrides": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "support": { "type": "object", "properties": { "supportEmail": { "type": "string" }, "supportUrl": { "type": "string" }, "documentationUrl": { "type": "string" }, "faqUrl": { "type": "string" }, "refundPolicyUrl": { "type": "string" }, "termsUrl": { "type": "string" }, "licenseUrl": { "type": "string" } }, "additionalProperties": true }, "emailIdentity": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "socialLinks": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "domains": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js" ] } }, "/api/license/v1/activate": { "post": { "summary": "Activate the current machine after direct serial/customer proof or a verified serial claim.", "description": "Generated native clients request device_credential_supported:true and retain the returned device_credential, plugin_session_id and newest validation_token privately. Device proof can renew after a short-lived token/session expires, but never bypasses revoked access, product/device binding or entitlement checks. device_credential_status:pending is incomplete enrollment, not an offline grant. Only an authorized signed offline_lease can support JUCE offline access. Side effects: Creates or reactivates a machine activation, ensures entitlement state, marks serial redeemed/billing eligible where applicable, records events, and issues a validation token.", "externalDocs": { "url": "https://www.soundsync.dev/docs/licensing/serial-activation" }, "parameters": [], "responses": { "200": { "description": "status activated, activationId, validation_token, entitlement_id, customer, max_activations, remaining, productId, grace_expires_at, offline_grace_days.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "activationId": { "type": "integer", "minimum": 1 }, "validation_token": { "type": "string" }, "entitlement_id": { "type": "integer", "minimum": 1 }, "customer": { "type": "object", "properties": {}, "additionalProperties": true }, "productId": { "type": "integer", "minimum": 1 }, "device_credential": { "type": "string", "description": "Private product/device-bound renewal proof. Returned when device_credential_supported is true and enrollment succeeds. Protect it in native secure storage; it is not a portal/library token or an offline grant." }, "device_credential_status": { "type": "string", "enum": [ "ready", "pending" ], "description": "pending means renewal enrollment is incomplete, even when activation was otherwise authorized. Follow the maintained client retry and access decision; do not manufacture offline authorization." }, "plugin_session_id": { "type": "string", "description": "Private short-lived plugin license session. Distinct from durable device_credential and customer library tokens." }, "plugin_session_expires_at": { "type": "string", "format": "date-time", "description": "Expiry of plugin_session_id, not the offline grace deadline." }, "max_activations": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "grace_expires_at": { "type": [ "string", "null" ] }, "offline_grace_days": { "type": "integer", "minimum": 0 }, "offline_grace": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "days": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "offline_lease": { "type": "string", "description": "Optional signed JSON envelope issued only by successful authorized activation/validation with a positive grace period and configured signer. Contains alg, kid, base64 payload and signature. Verify with trusted package public keys; decoding alone is not authorization. Never log customer grants." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Product, app, credential, environment, and machine scoped.", "x-request-fields": [ "instance_id: string", "machine_id: string", "product_id: integer", "plugin_version: string", "version: string", "license_key: string", "serial: string", "email: string", "validation_token: string", "token: string", "activationId: value", "licenseReference: string", "plugin_session_id: string", "device_credential: string. Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio.", "license_kind: serial | email_entitlement", "device_credential_supported: boolean. Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias.", "claim_id: string", "claim_activation_token: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js", "services/pluginLicenseSessionService.js", "packages/juce/native/src/ApiModels.cpp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string" }, "machine_id": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "license_key": { "type": "string" }, "serial": { "type": "string" }, "email": { "type": "string", "format": "email" }, "validation_token": { "type": "string" }, "token": { "type": "string" }, "activationId": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "licenseReference": { "type": "string" }, "plugin_session_id": { "type": "string" }, "device_credential": { "type": "string", "description": "Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio." }, "license_kind": { "type": "string", "enum": [ "serial", "email_entitlement" ] }, "device_credential_supported": { "type": "boolean", "description": "Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias." }, "claim_id": { "type": "string" }, "claim_activation_token": { "type": "string" } }, "additionalProperties": true, "anyOf": [ { "required": [ "instance_id" ] }, { "required": [ "machine_id" ] } ] } } } } } }, "/api/license/v1/activation/start": { "post": { "summary": "Begin email-code activation for a product entitlement", "description": "Can create a challenge and send an email. The same generic pending state can be returned when access is unavailable; it does not prove entitlement or email delivery.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/licensing" }, "parameters": [], "responses": { "200": { "description": "200: ok, status pending_email_verification, code PENDING_EMAIL_VERIFICATION; challengeId, emailSent, and branding can be present.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "const": "pending_email_verification" }, "code": { "const": "PENDING_EMAIL_VERIFICATION" }, "challengeId": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "emailSent": { "type": "boolean" }, "branding": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "status", "code" ], "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Product, customer email, and machine identity.", "x-request-fields": [ "email: string (required)", "instance_id: string (required)", "device_label: string", "plugin_version: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "instance_id": { "type": "string" }, "device_label": { "type": "string" }, "plugin_version": { "type": "string" } }, "required": [ "email", "instance_id" ], "additionalProperties": true } } } } } }, "/api/license/v1/activation/verify-email": { "post": { "summary": "Verify the six-digit code and complete email-entitlement activation", "description": "Codes expire after 15 minutes and are one-use. Five incorrect attempts lock the challenge. Invalid, expired, missing, or locked codes return 400; product credential and access checks still apply.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/licensing" }, "parameters": [], "responses": { "200": { "description": "200: activation result if the code and current entitlement/device checks pass.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "activationId": { "type": "integer", "minimum": 1 }, "validation_token": { "type": "string" }, "entitlement_id": { "type": "integer", "minimum": 1 }, "customer": { "type": "object", "properties": {}, "additionalProperties": true }, "productId": { "type": "integer", "minimum": 1 }, "device_credential": { "type": "string", "description": "Private product/device-bound renewal proof. Returned when device_credential_supported is true and enrollment succeeds. Protect it in native secure storage; it is not a portal/library token or an offline grant." }, "device_credential_status": { "type": "string", "enum": [ "ready", "pending" ], "description": "pending means renewal enrollment is incomplete, even when activation was otherwise authorized. Follow the maintained client retry and access decision; do not manufacture offline authorization." }, "plugin_session_id": { "type": "string", "description": "Private short-lived plugin license session. Distinct from durable device_credential and customer library tokens." }, "plugin_session_expires_at": { "type": "string", "format": "date-time", "description": "Expiry of plugin_session_id, not the offline grace deadline." }, "max_activations": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "grace_expires_at": { "type": [ "string", "null" ] }, "offline_grace_days": { "type": "integer", "minimum": 0 }, "offline_grace": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "days": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "offline_lease": { "type": "string", "description": "Optional signed JSON envelope issued only by successful authorized activation/validation with a positive grace period and configured signer. Contains alg, kid, base64 payload and signature. Verify with trusted package public keys; decoding alone is not authorization. Never log customer grants." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Same product, email, and machine as the challenge.", "x-request-fields": [ "email: string (required)", "instance_id: string (required)", "device_label: string", "plugin_version: string", "device_credential_supported: boolean. Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias.", "code: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "instance_id": { "type": "string" }, "device_label": { "type": "string" }, "plugin_version": { "type": "string" }, "device_credential_supported": { "type": "boolean", "description": "Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias." }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "email", "instance_id", "code" ], "additionalProperties": true } } } } } }, "/api/license/v1/claim": { "post": { "summary": "Start a serial claim when customer identity or email verification is required.", "description": "Requires a serial/license_key, customer email and instance_id (machine_id is an alias). A pending response includes claim_id and emailSent:true; it does not activate the device. 503 VERIFICATION_EMAIL_FAILED with emailSent:false is not confirmed delivery or authorization: retry the claim deliberately after recovery. Owner mismatch/login-required errors do not transfer ownership. Keep the same serial and machine through claim-status and final activation. A compatibility CUSTOMER_ACCOUNT_EXISTS response directs account login/password recovery, not offline access. Side effects: Creates or restores a pending serial claim and can send the verification email.", "externalDocs": { "url": "https://www.soundsync.dev/docs/licensing/serial-activation" }, "parameters": [], "responses": { "200": { "description": "pending_email_verification with claim_id/claimId and emailSent when verification is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "code": { "type": "string" }, "claim_id": { "type": "string" }, "claimId": { "type": "string" }, "emailSent": { "type": "boolean" }, "message": { "type": "string" }, "nextAction": { "type": "string" }, "passwordResetUrl": { "type": "string" }, "claimRequired": { "type": "boolean" }, "ownerVerificationRequired": { "type": "boolean" }, "requiredFields": { "type": "array", "items": { "type": "string" } }, "claim_activation_token": { "type": "string" }, "claimActivationToken": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Product, app, credential, environment, and machine scoped.", "x-request-fields": [ "instance_id: string", "machine_id: string", "product_id: integer", "plugin_version: string", "version: string", "license_key: string (required)", "email: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "IDENTITY_FIELDS_REQUIRED", "INVALID_EMAIL", "SERIAL_OWNER_EMAIL_MISMATCH", "SERIAL_OWNER_LOGIN_REQUIRED", "VERIFICATION_EMAIL_FAILED" ], "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js", "services/licenseSerialClaimService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string" }, "machine_id": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "license_key": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "license_key", "email" ], "additionalProperties": true, "anyOf": [ { "required": [ "instance_id" ] }, { "required": [ "machine_id" ] } ] } } } } } }, "/api/license/v1/claim-status": { "get": { "summary": "Restore a pending serial claim and receive claim activation material after email verification.", "description": "HTTP 200 may mean pending_email_verification, verified or identity_required; inspect status/code and ok. Only verified returns claim_activation_token for a separate final POST /activate on the same product/serial/machine. 400 VERIFICATION_RESTART_REQUIRED means the link expired or was not sent: submit email and serial to /claim again instead of polling forever. A confirmed owner/access denial is not offline grace. Pending polling/finalization can retry transient outages without discarding the saved claim. GET is a compatibility transport; prefer POST to keep serial/proof out of URLs and logs. Side effects: Does not activate the machine. The client must call /activate after verified status.", "externalDocs": { "url": "https://www.soundsync.dev/docs/licensing/serial-activation" }, "parameters": [ { "name": "license_key", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "claim_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "pending_email_verification, verified with claim_activation_token/claimActivationToken, or identity_required. Inspect status/code and ok; HTTP 200 alone is not activation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "code": { "type": "string" }, "claim_id": { "type": "string" }, "claimId": { "type": "string" }, "emailSent": { "type": "boolean" }, "message": { "type": "string" }, "nextAction": { "type": "string" }, "passwordResetUrl": { "type": "string" }, "claimRequired": { "type": "boolean" }, "ownerVerificationRequired": { "type": "boolean" }, "requiredFields": { "type": "array", "items": { "type": "string" } }, "claim_activation_token": { "type": "string" }, "claimActivationToken": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Product, app, credential, environment, and machine scoped.", "x-request-fields": [ "query license_key: string (required)", "query instance_id: string (required)", "query claim_id: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "VERIFICATION_RESTART_REQUIRED" ], "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js", "services/licenseSerialClaimService.js" ] }, "post": { "summary": "Restore a pending serial claim and receive claim activation material after email verification.", "description": "HTTP 200 may mean pending_email_verification, verified or identity_required; inspect status/code and ok. Only verified returns claim_activation_token for a separate final POST /activate on the same product/serial/machine. 400 VERIFICATION_RESTART_REQUIRED means the link expired or was not sent: submit email and serial to /claim again instead of polling forever. A confirmed owner/access denial is not offline grace. Pending polling/finalization can retry transient outages without discarding the saved claim. GET is a compatibility transport; prefer POST to keep serial/proof out of URLs and logs. Side effects: Does not activate the machine. The client must call /activate after verified status.", "externalDocs": { "url": "https://www.soundsync.dev/docs/licensing/serial-activation" }, "parameters": [], "responses": { "200": { "description": "pending_email_verification, verified with claim_activation_token/claimActivationToken, or identity_required. Inspect status/code and ok; HTTP 200 alone is not activation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "code": { "type": "string" }, "claim_id": { "type": "string" }, "claimId": { "type": "string" }, "emailSent": { "type": "boolean" }, "message": { "type": "string" }, "nextAction": { "type": "string" }, "passwordResetUrl": { "type": "string" }, "claimRequired": { "type": "boolean" }, "ownerVerificationRequired": { "type": "boolean" }, "requiredFields": { "type": "array", "items": { "type": "string" } }, "claim_activation_token": { "type": "string" }, "claimActivationToken": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Product, app, credential, environment, and machine scoped.", "x-request-fields": [ "instance_id: string (required)", "machine_id: string", "product_id: integer", "plugin_version: string", "version: string", "license_key: string (required)", "claim_id: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "VERIFICATION_RESTART_REQUIRED" ], "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js", "services/licenseSerialClaimService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string" }, "machine_id": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "license_key": { "type": "string" }, "claim_id": { "type": "string" } }, "required": [ "license_key", "instance_id" ], "additionalProperties": true } } } } } }, "/api/license/v1/customer-login/activate": { "post": { "summary": "Activate by customer account identity when the product supports account/login activation.", "description": "The token branch resolves the verified customer identity from the token. Never persist account passwords or substitute a developer token; product ownership and device checks still apply. The direct email/password compatibility branch cannot complete a two-factor challenge: it returns 401 TWO_FACTOR_REQUIRED for an enabled account. Current JUCE 0.7.3 and HISE Native 0.5.2 clients first call /api/auth/login with role:customer, continue with twoFactorToken/twoFactorCode when requested, then pass the verified customer token as customer_token here. Never substitute the challenge token or a developer session. Entitlement and machine checks still apply. Regenerate and rebuild older packages; see the dedicated customer-login guide for the complete conversation. When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks.", "externalDocs": { "url": "https://www.soundsync.dev/docs/licensing/customer-login-activation" }, "parameters": [], "responses": { "200": { "description": "activation result with validation token, entitlement/customer details, device limit and subscription state where applicable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "activationId": { "type": "integer", "minimum": 1 }, "validation_token": { "type": "string" }, "entitlement_id": { "type": "integer", "minimum": 1 }, "customer": { "type": "object", "properties": {}, "additionalProperties": true }, "productId": { "type": "integer", "minimum": 1 }, "device_credential": { "type": "string", "description": "Private product/device-bound renewal proof. Returned when device_credential_supported is true and enrollment succeeds. Protect it in native secure storage; it is not a portal/library token or an offline grant." }, "device_credential_status": { "type": "string", "enum": [ "ready", "pending" ], "description": "pending means renewal enrollment is incomplete, even when activation was otherwise authorized. Follow the maintained client retry and access decision; do not manufacture offline authorization." }, "plugin_session_id": { "type": "string", "description": "Private short-lived plugin license session. Distinct from durable device_credential and customer library tokens." }, "plugin_session_expires_at": { "type": "string", "format": "date-time", "description": "Expiry of plugin_session_id, not the offline grace deadline." }, "max_activations": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "grace_expires_at": { "type": [ "string", "null" ] }, "offline_grace_days": { "type": "integer", "minimum": 0 }, "offline_grace": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "days": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "offline_lease": { "type": "string", "description": "Optional signed JSON envelope issued only by successful authorized activation/validation with a positive grace period and configured signer. Contains alg, kid, base64 payload and signature. Verify with trusted package public keys; decoding alone is not authorization. Never log customer grants." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Product, app, credential, environment, and machine scoped.", "x-request-fields": [ "instance_id: string", "machine_id: string", "product_id: integer", "plugin_version: string", "version: string", "device_credential_supported: boolean. Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias.", "email: string", "password: string", "customer_token: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "CUSTOMER_LOGIN_INVALID", "TWO_FACTOR_REQUIRED", "EMAIL_VERIFICATION_REQUIRED", "SESSION_VERIFICATION_UNAVAILABLE", "LIBRARY_SESSION_REVOKED" ], "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js", "services/customerLibraryIdentityService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string" }, "machine_id": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "device_credential_supported": { "type": "boolean", "description": "Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias." }, "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "customer_token": { "type": "string", "minLength": 1 } }, "additionalProperties": true, "allOf": [ { "anyOf": [ { "required": [ "instance_id" ] }, { "required": [ "machine_id" ] } ] }, { "anyOf": [ { "required": [ "email", "password" ] }, { "required": [ "customer_token" ] } ] } ] } } } } } }, "/api/license/v1/deactivate": { "post": { "summary": "Deactivate this machine and release local access.", "description": "Send the retained device_credential or permitted plugin_session_id with the same product and machine identity. A supported validation-token proof is a separate compatibility path: send the current validation_token with its serial/email or activation context. Product credential headers, a serial and a machine ID alone are not deactivation proof. Missing or invalid compatibility proof returns 401 deactivate_validation_token_required or deactivate_validation_token_invalid. A nonempty proof field only satisfies the request shape; the server still verifies signature, ownership, product, machine and activation generation. Confirm status/code and deactivation flags before claiming server slot release. JUCE locks locally and preserves pending proof until confirmed; deactivation does not issue a fresh offline grant. Side effects: Sets deactivated_at on the activation, records an event, and should cause the client to delete local activation state.", "externalDocs": { "url": "https://www.soundsync.dev/docs/licensing/deactivation" }, "parameters": [], "responses": { "200": { "description": "status deactivated, code DEVICE_DEACTIVATED, remaining_activations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "mayOpenProduct": { "type": "boolean" }, "activation_deactivated": { "type": "boolean" }, "plugin_session_deactivated": { "type": "boolean" }, "activation_id": { "type": "integer", "minimum": 1 }, "activationId": { "type": "integer", "minimum": 1 }, "current_activations": { "type": "integer", "minimum": 0 }, "max_activations": { "type": "integer", "minimum": 0 }, "remaining_activations": { "type": "integer", "minimum": 0 }, "serial_status": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Product, app, credential, environment, and machine scoped.", "x-request-fields": [ "instance_id: string", "machine_id: string", "product_id: integer", "plugin_version: string", "version: string", "license_key: string", "serial: string", "email: string", "validation_token: string", "token: string", "activationId: value", "licenseReference: string", "plugin_session_id: string", "device_credential: string. Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio.", "license_kind: serial | email_entitlement", "claim_id: string", "claim_activation_token: string", "deviceCredential: string", "pluginSessionId: string", "session_id: string", "sessionId: string", "soundSyncSessionId: string", "soundsync_session_id: string", "validationToken: string", "new_token: string", "newToken: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "deactivate_validation_token_required", "deactivate_validation_token_invalid", "DEVICE_ACTIVATION_NOT_FOUND" ], "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js", "services/pluginLicenseSessionService.js", "packages/juce/native/src/ApiModels.cpp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string" }, "machine_id": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "license_key": { "type": "string" }, "serial": { "type": "string" }, "email": { "type": "string", "format": "email" }, "validation_token": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "activationId": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "licenseReference": { "type": "string" }, "plugin_session_id": { "type": "string", "minLength": 1 }, "device_credential": { "type": "string", "description": "Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio.", "minLength": 1 }, "license_kind": { "type": "string", "enum": [ "serial", "email_entitlement" ] }, "claim_id": { "type": "string" }, "claim_activation_token": { "type": "string" }, "deviceCredential": { "type": "string", "minLength": 1 }, "pluginSessionId": { "type": "string", "minLength": 1 }, "session_id": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 }, "soundSyncSessionId": { "type": "string", "minLength": 1 }, "soundsync_session_id": { "type": "string", "minLength": 1 }, "validationToken": { "type": "string", "minLength": 1 }, "new_token": { "type": "string", "minLength": 1 }, "newToken": { "type": "string", "minLength": 1 } }, "additionalProperties": true, "anyOf": [ { "required": [ "instance_id" ] }, { "required": [ "machine_id" ] } ], "allOf": [ { "anyOf": [ { "required": [ "device_credential" ] }, { "required": [ "deviceCredential" ] }, { "required": [ "plugin_session_id" ] }, { "required": [ "pluginSessionId" ] }, { "required": [ "session_id" ] }, { "required": [ "sessionId" ] }, { "required": [ "soundSyncSessionId" ] }, { "required": [ "soundsync_session_id" ] }, { "required": [ "validation_token" ] }, { "required": [ "token" ] }, { "required": [ "validationToken" ] }, { "required": [ "new_token" ] }, { "required": [ "newToken" ] } ] } ] } } } } } }, "/api/license/v1/library-token": { "get": { "summary": "Issue or return a customer library token for plugin/webview customer-library access.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-library" }, "parameters": [ { "name": "instance_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "validation_token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "plugin_session_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Library token response used by HISE storefront package and webview-library flows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "token": { "type": "string" }, "library_token": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Customer/library session scope.", "x-request-fields": [ "query instance_id: string", "query validation_token: string", "query plugin_session_id: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js" ] }, "post": { "summary": "Issue or return a customer library token for plugin/webview customer-library access.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-library" }, "parameters": [], "responses": { "200": { "description": "Library token response used by HISE storefront package and webview-library flows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "token": { "type": "string" }, "library_token": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Customer/library session scope.", "x-request-fields": [ "instance_id: string", "machine_id: string", "product_id: integer", "plugin_version: string", "version: string", "license_key: string", "serial: string", "email: string", "validation_token: string", "token: string", "activationId: value", "licenseReference: string", "plugin_session_id: string", "key: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string" }, "machine_id": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "license_key": { "type": "string" }, "serial": { "type": "string" }, "email": { "type": "string", "format": "email" }, "validation_token": { "type": "string" }, "token": { "type": "string" }, "activationId": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "licenseReference": { "type": "string" }, "plugin_session_id": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/license/v1/validate": { "post": { "summary": "Validate cached activation state on startup or during periodic revalidation.", "description": "Generated native clients request device_credential_supported:true and retain the returned device_credential, plugin_session_id and newest validation_token privately. Device proof can renew after a short-lived token/session expires, but never bypasses revoked access, product/device binding or entitlement checks. device_credential_status:pending is incomplete enrollment, not an offline grant. Only an authorized signed offline_lease can support JUCE offline access. Side effects: Refreshes validation state and token when allowed. Explicit denials force lock and must not use offline grace.", "externalDocs": { "url": "https://www.soundsync.dev/docs/licensing/validate-on-startup" }, "parameters": [], "responses": { "200": { "description": "active/denied state, rotated validation token, last validation timestamps, offline grace fields, subscription/license state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "activationId": { "type": "integer", "minimum": 1 }, "validation_token": { "type": "string" }, "entitlement_id": { "type": "integer", "minimum": 1 }, "customer": { "type": "object", "properties": {}, "additionalProperties": true }, "productId": { "type": "integer", "minimum": 1 }, "device_credential": { "type": "string", "description": "Private product/device-bound renewal proof. Returned when device_credential_supported is true and enrollment succeeds. Protect it in native secure storage; it is not a portal/library token or an offline grant." }, "device_credential_status": { "type": "string", "enum": [ "ready", "pending" ], "description": "pending means renewal enrollment is incomplete, even when activation was otherwise authorized. Follow the maintained client retry and access decision; do not manufacture offline authorization." }, "plugin_session_id": { "type": "string", "description": "Private short-lived plugin license session. Distinct from durable device_credential and customer library tokens." }, "plugin_session_expires_at": { "type": "string", "format": "date-time", "description": "Expiry of plugin_session_id, not the offline grace deadline." }, "max_activations": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "grace_expires_at": { "type": [ "string", "null" ] }, "offline_grace_days": { "type": "integer", "minimum": 0 }, "offline_grace": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "days": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "offline_lease": { "type": "string", "description": "Optional signed JSON envelope issued only by successful authorized activation/validation with a positive grace period and configured signer. Contains alg, kid, base64 payload and signature. Verify with trusted package public keys; decoding alone is not authorization. Never log customer grants." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Product, app, credential, environment, and machine scoped.", "x-request-fields": [ "instance_id: string", "machine_id: string", "product_id: integer", "plugin_version: string", "version: string", "license_key: string", "serial: string", "email: string", "validation_token: string", "token: string", "activationId: value", "licenseReference: string", "plugin_session_id: string", "device_credential: string. Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio.", "license_kind: serial | email_entitlement", "device_credential_supported: boolean. Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias.", "claim_id: string", "claim_activation_token: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js", "services/pluginLicenseSessionService.js", "packages/juce/native/src/ApiModels.cpp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string" }, "machine_id": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "license_key": { "type": "string" }, "serial": { "type": "string" }, "email": { "type": "string", "format": "email" }, "validation_token": { "type": "string" }, "token": { "type": "string" }, "activationId": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "licenseReference": { "type": "string" }, "plugin_session_id": { "type": "string" }, "device_credential": { "type": "string", "description": "Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio." }, "license_kind": { "type": "string", "enum": [ "serial", "email_entitlement" ] }, "device_credential_supported": { "type": "boolean", "description": "Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias." }, "claim_id": { "type": "string" }, "claim_activation_token": { "type": "string" } }, "additionalProperties": true, "anyOf": [ { "required": [ "instance_id" ] }, { "required": [ "machine_id" ] } ] } } } } } }, "/api/license/v1/webview-library": { "get": { "summary": "Return webview customer-library payload for plugin-hosted library experiences.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-library" }, "parameters": [ { "name": "instance_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "validation_token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "plugin_session_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer library payload suitable for in-plugin WebView use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "libraryToken": { "type": "string" }, "library_token": { "type": "string" }, "download_token": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Customer library and product/storefront scope.", "x-request-fields": [ "query instance_id: string", "query validation_token: string", "query plugin_session_id: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js" ] }, "post": { "summary": "Return webview customer-library payload for plugin-hosted library experiences.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/customer-library" }, "parameters": [], "responses": { "200": { "description": "Customer library payload suitable for in-plugin WebView use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "libraryToken": { "type": "string" }, "library_token": { "type": "string" }, "download_token": { "type": "string" }, "expiresIn": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)", "x-access-scope": "Customer library and product/storefront scope.", "x-request-fields": [ "instance_id: string", "machine_id: string", "product_id: integer", "plugin_version: string", "version: string", "license_key: string", "serial: string", "email: string", "validation_token: string", "token: string", "activationId: value", "licenseReference: string", "plugin_session_id: string", "key: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "ProductAppId": [], "ProductPluginKey": [], "ProductPluginSecret": [] }, { "ProductAppId": [], "ProductId": [], "NativePublicClient": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/licenseRoutes.js", "controllers/licenseController.js", "middleware/authMiddleware.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string" }, "machine_id": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "license_key": { "type": "string" }, "serial": { "type": "string" }, "email": { "type": "string", "format": "email" }, "validation_token": { "type": "string" }, "token": { "type": "string" }, "activationId": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "licenseReference": { "type": "string" }, "plugin_session_id": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/marketplace/assets/products/{productId}/{placementType}": { "get": { "summary": "Resolve artwork for a public marketplace product and placement", "description": "Default resolution can prepare missing artwork; not a pure health check. Public caching is bounded. Wide/editorial placements do not use an arbitrary source-image fallback. Default resolution can prepare missing artwork; ensure=false disables on-demand preparation for this request. A returned asset is placement-specific, not an arbitrary source-image fallback.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/marketplace" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "placementType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "viewport", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "campaign", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "ensure", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "" } ], "responses": { "200": { "description": "{ asset: ... }; inspect the selected asset URL and placement metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "placementType": { "type": "string" }, "assetType": { "type": "string" }, "active": { "type": "boolean" }, "approvalStatus": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "sourceClassification": { "type": "string" }, "classificationConfidence": { "type": "string" }, "usageRoles": { "type": "array", "items": { "type": "string" } }, "primaryRole": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Publicly visible marketplace products and valid placements only.", "x-request-fields": [ "query viewport: string", "query campaign: string", "query ensure: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceAssetRoutes.js", "services/marketplaceAssetBuilderService.js" ] } }, "/api/marketplace/categories/{slug}": { "get": { "summary": "Category discovery", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: category, products, pagination, generatedAt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/collections": { "get": { "summary": "Published collections", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: collections, pagination, generatedAt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "collections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "productCount": { "type": "integer" } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/collections/{slug}": { "get": { "summary": "Collection detail", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: collection, products, pagination, generatedAt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "collection": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "productCount": { "type": "integer" } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/deals": { "get": { "summary": "Published deals", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: products, pagination, generatedAt, sort.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sort": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/developers": { "get": { "summary": "Customer developer directory", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: developers, pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "developers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "shortBio": { "type": "string" } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/developers/{slug}": { "get": { "summary": "Fetch public marketplace developer profile.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/marketplace" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "developer profile and public product context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "developer": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "shortBio": { "type": "string" } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "featuredProducts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Use the authentication and resource scope specified for this operation.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/free": { "get": { "summary": "Supported free-product discovery", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: products, pagination, generatedAt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/homepage": { "get": { "summary": "Customer homepage content", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: hero, sections, generatedAt, cacheKey, sectionOrdering, viewer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hero": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "status": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "title": { "type": "string" }, "href": { "type": "string" }, "source": { "type": "string" }, "priority": { "type": "number" } }, "additionalProperties": true } }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cacheKey": { "type": "string" }, "sectionOrdering": { "type": "array", "items": { "type": "string" } }, "viewer": { "type": "object", "properties": { "authenticated": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/new-releases": { "get": { "summary": "Recent published releases", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: products, pagination, generatedAt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/products": { "get": { "summary": "Search public marketplace products.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/marketplace" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "products[], pagination/facets as returned by marketplace product service.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Listed and visible marketplace product scope.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/products/{id}": { "get": { "summary": "Fetch one public marketplace product.", "description": "Side effects: Retrieves the authorized resource; any preparation or event recording is described in the operation notes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/marketplace" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "{ product } or PRODUCT_NOT_FOUND.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Use the authentication and resource scope specified for this operation.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/marketplace/products/{id}/list": { "post": { "summary": "List developer-owned product in marketplace.", "description": "Requires the permitted developer product. Listing is optional; no placement or sales guarantee is made. Side effects: Updates marketplace_status/visibility through marketplace product service.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/marketplace" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "{ product } listed state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Use the authentication and resource scope specified for this operation.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/marketplace/products/{id}/unlist": { "post": { "summary": "Unlist developer-owned product from marketplace.", "description": "Side effects: Updates marketplace visibility.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/marketplace" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "{ product } unlisted state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Use the authentication and resource scope specified for this operation.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/marketplace/search": { "get": { "summary": "Customer product search", "description": "An empty q returns 400 SEARCH_QUERY_REQUIRED.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: products, pagination, generatedAt, q, developers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true }, "generatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "q": { "type": "string" }, "developers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "shortBio": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query q: string (required)", "query page: integer", "query limit: integer", "query search: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/marketplaceRoutes.js", "services/publicMarketplaceHomeService.js", "services/marketplaceProductService.js" ] } }, "/api/partner-portal/api-keys": { "get": { "summary": "Read reseller api-keys", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Returns only member-accessible partner records. Historical customer identity, serials, commercial terms and conversations are private. Lists do not execute a payout, authorize a download or grant product ownership.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: api_keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_keys": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "query relationshipId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/campaigns": { "get": { "summary": "Read reseller campaigns", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Returns only member-accessible partner records. Historical customer identity, serials, commercial terms and conversations are private. Lists do not execute a payout, authorize a download or grant product ownership.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: campaigns.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "query relationshipId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/conversations": { "get": { "summary": "Read reseller conversations", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Returns only member-accessible partner records. Historical customer identity, serials, commercial terms and conversations are private. Lists do not execute a payout, authorize a download or grant product ownership.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "query relationshipId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] }, "post": { "summary": "Start a conversation with the related developer", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Eligible active owner/admin/technical/support/accounting/marketing membership is required for conversation writes. Never attach customer credentials or unnecessary personal records.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: thread, message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "thread": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "message": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "relationshipId: integer", "relationship_id: integer", "subject: string (required)", "body: string", "message: string", "threadType: string", "linkedProductId: integer", "linkedExternalOrderId: integer", "attachments: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "relationshipId": { "type": "integer", "minimum": 1 }, "relationship_id": { "type": "integer", "minimum": 1 }, "subject": { "type": "string" }, "body": { "type": "string" }, "message": { "type": "string" }, "threadType": { "type": "string" }, "linkedProductId": { "type": "integer", "minimum": 1 }, "linkedExternalOrderId": { "type": "integer", "minimum": 1 }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true, "required": [ "subject" ], "allOf": [ { "anyOf": [ { "required": [ "relationshipId" ] }, { "required": [ "relationship_id" ] } ] }, { "anyOf": [ { "required": [ "body" ] }, { "required": [ "message" ] } ] } ] } } } } } }, "/api/partner-portal/conversations/{threadId}/messages": { "post": { "summary": "Reply to an accessible conversation", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Uses the same conversation-write role check; a thread ID cannot expand partner access.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "body: string", "message: string", "attachments: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "message": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true, "anyOf": [ { "required": [ "body" ] }, { "required": [ "message" ] } ] } } } } } }, "/api/partner-portal/directory/developers": { "get": { "summary": "Read developers available for relationship requests", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: developers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "developers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/invitations/accept": { "post": { "summary": "Accept the intended reseller invitation", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Private token must match the signed-in intended recipient with verified email. An expired/used token returns 410. Acceptance does not guarantee owner approval, an active relationship or API credentials.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: partner_id, status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "partner_id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "The requested token or saved operation has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "token: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "INVITATION_EXPIRED", "INVITED_EMAIL_REQUIRED", "EMAIL_VERIFICATION_REQUIRED", "MEMBERSHIP_CONFLICT" ], "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js", "services/partnerResellerOnboardingService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": true } } } } } }, "/api/partner-portal/licenses": { "get": { "summary": "Read reseller licenses", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Returns only member-accessible partner records. Historical customer identity, serials, commercial terms and conversations are private. Lists do not execute a payout, authorize a download or grant product ownership.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: licenses.", "content": { "application/json": { "schema": { "type": "object", "properties": { "licenses": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "query relationshipId: integer", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/me": { "get": { "summary": "Read signed-in reseller memberships and configured API availability", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Available before a membership has been accepted. No membership or partner_api_enabled:false is not permission to bypass approval. Affiliate/collaborator program routes have their own recipient checks.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: user, memberships, partner_api_enabled, portal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "email": { "type": "string", "format": "email" }, "role": { "type": "string" }, "is_reseller": { "type": "boolean" } }, "additionalProperties": true }, "memberships": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "partner_api_enabled": { "type": "boolean" }, "portal": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/orders": { "get": { "summary": "Read reseller orders", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Returns only member-accessible partner records. Historical customer identity, serials, commercial terms and conversations are private. Lists do not execute a payout, authorize a download or grant product ownership.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "query relationshipId: integer", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/overview": { "get": { "summary": "Read reseller overview and accessible relationships", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: portal, memberships, pending_approval, overview, relationships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "portal": { "type": "string" }, "memberships": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "pending_approval": { "type": "boolean" }, "overview": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "relationships": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/products": { "get": { "summary": "Read reseller products", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Returns only member-accessible partner records. Historical customer identity, serials, commercial terms and conversations are private. Lists do not execute a payout, authorize a download or grant product ownership.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "query relationshipId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/profile/{partnerId}": { "patch": { "summary": "Submit reseller profile details for review", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Reseller owner/admin membership is required. Saves a pending profile for review rather than automatically replacing approved public identity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: partner, status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "partner": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "status": { "const": "pending_review" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "name: string (required)", "websiteUrl: string", "summary: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js", "services/partnerResellerOnboardingService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160 }, "websiteUrl": { "type": "string" }, "summary": { "type": "string", "maxLength": 1000 } }, "required": [ "name" ], "additionalProperties": true } } } } } }, "/api/partner-portal/programs": { "get": { "summary": "List agreements for the signed-in recipient.", "description": "Recipient-scoped programs only. Participation does not grant developer workspace or reseller access. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "200": { "description": "Recipient-scoped agreements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "kind": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "terms_version": { "type": "integer" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "rate_bps": { "type": "integer" } }, "additionalProperties": true } }, "aggregate_clicks": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "live_accounting_available": { "type": "boolean" }, "summary": { "type": "object", "properties": { "agreement_count": { "type": "integer" }, "active_count": { "type": "integer" }, "pending_acceptance_count": { "type": "integer" }, "aggregate_clicks": { "type": [ "string", "null" ] }, "referral_counts_available": { "type": "boolean" } }, "additionalProperties": true }, "permissions": { "type": "object", "properties": { "can_manage": { "type": "boolean" } }, "additionalProperties": true }, "migration_required": { "type": "boolean" }, "preview_notice": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Only the signed-in recipient's agreements, acceptance, balances and payout destination.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js" ] } }, "/api/partner-portal/programs/{id}/live-consent": { "post": { "summary": "Recipient authorizes the applicable live terms.", "description": "Side effects: Recipient authorizes the applicable live terms. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted recipient consent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "party": { "enum": [ "developer", "recipient" ] }, "terms_version": { "type": "integer", "minimum": 1 }, "policy_version": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Only the signed-in recipient's agreements, acceptance, balances and payout destination.", "x-request-fields": [ "accept: true (required)", "terms_version: integer (required)", "policy_version: \"soundsync-managed-live-v1\" (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accept": { "const": true }, "terms_version": { "type": "integer", "minimum": 1 }, "policy_version": { "const": "soundsync-managed-live-v1" } }, "required": [ "accept", "terms_version", "policy_version" ], "additionalProperties": true } } } } } }, "/api/partner-portal/programs/accounting": { "get": { "summary": "Read the recipient's own balances and transfer history.", "description": "Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "200": { "description": "Accounting summary; external amounts remain separately unfunded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rollout_enabled": { "type": "boolean" }, "balances": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "balance_details": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "reversals": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "transfers": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "developer_earnings": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "unfunded_earnings": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "consents": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "destinations": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "payout_schedule": { "type": "object", "properties": { "hold_days": { "type": "integer", "minimum": 0 }, "next_run_date": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Only the signed-in recipient's agreements, acceptance, balances and payout destination.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ] } }, "/api/partner-portal/programs/invitations/{token}": { "get": { "summary": "Read a private invitation for its intended recipient.", "description": "Never expose invitation tokens in public URLs or screenshots. Requires the signed-in intended recipient. Inspect the current version before accepting; a displayed invitation is not accepted terms or earnings. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation and displayed terms.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ] }, "kind": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "terms_version": { "type": "integer" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "rate_bps": { "type": "integer" } }, "additionalProperties": true } }, "aggregate_clicks": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "terms": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "invitation": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "terms_version": { "type": "integer" } }, "additionalProperties": true }, "preview_terms_version": { "type": "integer" }, "preview_notice": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Only the signed-in recipient's agreements, acceptance, balances and payout destination.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js" ] } }, "/api/partner-portal/programs/invitations/accept": { "post": { "summary": "Accept the displayed invitation terms.", "description": "These field names describe invitation acceptance, not live payment consent. The verified invited identity is required. Side effects: Accept the displayed invitation terms. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "200": { "description": "Accepted version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Only the signed-in recipient's agreements, acceptance, balances and payout destination.", "x-request-fields": [ "token: string (required)", "accept_preview_terms: true (required)", "preview_terms_version: string (required)", "payout_policy_version: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "accept_preview_terms": { "const": true }, "preview_terms_version": { "type": "string" }, "payout_policy_version": { "type": "string" } }, "required": [ "token", "accept_preview_terms", "preview_terms_version", "payout_policy_version" ], "additionalProperties": true } } } } } }, "/api/partner-portal/programs/payouts/paypal": { "post": { "summary": "Confirm the verified recipient email as the PayPal destination.", "description": "A destination change can impose a security hold; no arbitrary third-party email is accepted. Side effects: Confirm the verified recipient email as the PayPal destination. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "200": { "description": "Destination readiness and availability time.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "url": { "type": "string" }, "provider": { "type": "string" }, "available_at": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Only the signed-in recipient's agreements, acceptance, balances and payout destination.", "x-request-fields": [ "livemode: boolean (required)", "program: affiliate | collaborator", "confirm_verified_email: true (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "livemode": { "type": "boolean" }, "program": { "enum": [ "affiliate", "collaborator" ] }, "confirm_verified_email": { "const": true } }, "required": [ "livemode", "confirm_verified_email" ], "additionalProperties": true } } } } } }, "/api/partner-portal/programs/payouts/stripe": { "post": { "summary": "Start or inspect recipient Stripe Connect onboarding.", "description": "Onboarding is not a payout request. Use the returned URL privately. Side effects: Start or inspect recipient Stripe Connect onboarding. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "200": { "description": "ready:true or an onboarding url.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "url": { "type": "string" }, "provider": { "type": "string" }, "available_at": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Only the signed-in recipient's agreements, acceptance, balances and payout destination.", "x-request-fields": [ "livemode: boolean (required)", "program: affiliate | collaborator", "confirm_verified_email: true" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "livemode": { "type": "boolean" }, "program": { "enum": [ "affiliate", "collaborator" ] }, "confirm_verified_email": { "const": true } }, "required": [ "livemode" ], "additionalProperties": true } } } } } }, "/api/partner-portal/programs/payouts/stripe/refresh": { "post": { "summary": "Refresh the recipient Stripe destination readiness.", "description": "Side effects: Refresh the recipient Stripe destination readiness. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [], "responses": { "200": { "description": "Current Stripe destination readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "url": { "type": "string" }, "provider": { "type": "string" }, "available_at": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Only the signed-in recipient's agreements, acceptance, balances and payout destination.", "x-request-fields": [ "livemode: boolean (required)", "program: affiliate | collaborator", "confirm_verified_email: true" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerProgramRoutes.js", "services/partnerProgramService.js", "services/partnerProgramLiveService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "livemode": { "type": "boolean" }, "program": { "enum": [ "affiliate", "collaborator" ] }, "confirm_verified_email": { "const": true } }, "required": [ "livemode" ], "additionalProperties": true } } } } } }, "/api/partner-portal/relationships": { "get": { "summary": "Read reseller relationships", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: relationships.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/relationships/{relationshipId}": { "get": { "summary": "Read one accessible relationship and its related records", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship, products, recent_orders, licenses, api_keys, conversations, statements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "recent_orders": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "licenses": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "api_keys": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "conversations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "statements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/relationships/{relationshipId}/accept": { "post": { "summary": "Accept an eligible relationship request", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires eligible owner/admin membership, the correct request side and a supported current state.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner-portal/relationships/{relationshipId}/deny": { "post": { "summary": "Deny a relationship request", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires eligible owner/admin membership, the correct request side and a supported current state.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner-portal/relationships/{relationshipId}/manual-issue": { "post": { "summary": "Issue fulfillment through the gated reseller portal", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires fulfillment availability, an active eligible relationship, manual_issue_enabled and owner/admin/technical/support membership. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. external_order_id/externalOrderId and at least one mapped product_id or reseller_sku are required; items supports multiple lines, otherwise the top-level product selection is used. The external order API defines the full accepted pricing, mapping, replay and fulfillment response contract. A missing Idempotency-Key is derived from the relationship and external order ID; do not change the order ID to retry. This can fulfill customer access, not charge a SoundSync-managed payment or absorb external processing fees.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: review the response schema below.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "The requested token or saved operation has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "header Idempotency-Key: string", "external_order_id: string", "externalOrderId: string", "customer_email: string", "customer_name: string", "customer_country: string", "external_order_url: string", "currency: string", "payment_status: paid | refunded | partially_refunded | chargeback | cancelled | unknown", "purchased_at: string,null", "total_paid_cents: integer", "total_paid: number", "subtotal_cents: integer", "discount_total_cents: integer", "tax_total_cents: integer", "product_id: integer", "reseller_sku: string", "quantity: integer", "items: array", "idempotency_key: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "PARTNER_FULFILLMENT_DISABLED" ], "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_order_id": { "type": "string" }, "externalOrderId": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "customer_name": { "type": "string" }, "customer_country": { "type": "string" }, "external_order_url": { "type": "string" }, "currency": { "type": "string" }, "payment_status": { "type": "string", "enum": [ "paid", "refunded", "partially_refunded", "chargeback", "cancelled", "unknown" ] }, "purchased_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_paid_cents": { "type": "integer", "minimum": 0 }, "total_paid": { "type": "number" }, "subtotal_cents": { "type": "integer" }, "discount_total_cents": { "type": "integer" }, "tax_total_cents": { "type": "integer" }, "product_id": { "type": "integer", "minimum": 1 }, "reseller_sku": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "reseller_sku": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "unit_reported_price_cents": { "type": "integer" }, "line_total_cents": { "type": "integer" }, "external_line_item_id": { "type": "string" }, "external_product_id": { "type": "string" }, "external_variation_id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "idempotency_key": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/partner-portal/relationships/{relationshipId}/webhook-events": { "get": { "summary": "Read partner webhook events and delivery attempts", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: events, deliveries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "deliveries": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/relationships/{relationshipId}/webhooks": { "post": { "summary": "Manage the gated relationship webhook operation", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires fulfillment availability plus active owner/admin/technical membership. A disabled launch gate returns 410 PARTNER_FULFILLMENT_DISABLED before mutation. Creation requires a public HTTPS url; omitted events defaults to order.fulfilled, order.refunded, license.revoked and webhook.test. Creation or explicit rotateSecret/rotate_secret returns private signing material inside webhook, not a top-level secret. Test queues a synthetic event; accepted is not delivered and this portal test is not a status-edit operation.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "The requested token or saved operation has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "url: string (required)", "events: array", "status: active | paused | disabled", "description: string", "rotateSecret: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "PARTNER_FULFILLMENT_DISABLED" ], "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.fulfilled", "order.refunded", "license.revoked", "relationship.requested", "relationship.updated", "webhook.test" ] } }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "description": { "type": "string" }, "rotateSecret": { "type": "boolean" } }, "additionalProperties": true, "required": [ "url" ] } } } } } }, "/api/partner-portal/relationships/{relationshipId}/webhooks/{webhookId}": { "delete": { "summary": "Manage the gated relationship webhook operation", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires fulfillment availability plus active owner/admin/technical membership. A disabled launch gate returns 410 PARTNER_FULFILLMENT_DISABLED before mutation. Creation requires a public HTTPS url; omitted events defaults to order.fulfilled, order.refunded, license.revoked and webhook.test. Creation or explicit rotateSecret/rotate_secret returns private signing material inside webhook, not a top-level secret. Test queues a synthetic event; accepted is not delivered and this portal test is not a status-edit operation.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: deleted, id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": [ "integer", "string" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "The requested token or saved operation has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-error-codes": [ "PARTNER_FULFILLMENT_DISABLED" ], "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] }, "patch": { "summary": "Manage the gated relationship webhook operation", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires fulfillment availability plus active owner/admin/technical membership. A disabled launch gate returns 410 PARTNER_FULFILLMENT_DISABLED before mutation. Creation requires a public HTTPS url; omitted events defaults to order.fulfilled, order.refunded, license.revoked and webhook.test. Creation or explicit rotateSecret/rotate_secret returns private signing material inside webhook, not a top-level secret. Test queues a synthetic event; accepted is not delivered and this portal test is not a status-edit operation.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "The requested token or saved operation has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "url: string", "events: array", "status: active | paused | disabled", "description: string", "rotateSecret: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "PARTNER_FULFILLMENT_DISABLED" ], "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.fulfilled", "order.refunded", "license.revoked", "relationship.requested", "relationship.updated", "webhook.test" ] } }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "description": { "type": "string" }, "rotateSecret": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/partner-portal/relationships/{relationshipId}/webhooks/{webhookId}/test": { "post": { "summary": "Manage the gated relationship webhook operation", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires fulfillment availability plus active owner/admin/technical membership. A disabled launch gate returns 410 PARTNER_FULFILLMENT_DISABLED before mutation. Creation requires a public HTTPS url; omitted events defaults to order.fulfilled, order.refunded, license.revoked and webhook.test. Creation or explicit rotateSecret/rotate_secret returns private signing material inside webhook, not a top-level secret. Test queues a synthetic event; accepted is not delivered and this portal test is not a status-edit operation.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: success, event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "event": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "The requested token or saved operation has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "message: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "PARTNER_FULFILLMENT_DISABLED" ], "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner-portal/requests": { "post": { "summary": "Request a relationship with a developer", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires an active owner/admin reseller membership. developerId/developer_id is required; partnerId selects the authorized partner when needed. Reconcile an existing request instead of treating a repeated request as another approved relationship.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "developerId: integer", "developer_id: integer", "partnerId: integer", "partner_id: integer", "message: string", "note: string", "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "developerId": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "partnerId": { "type": "integer", "minimum": 1 }, "partner_id": { "type": "integer", "minimum": 1 }, "message": { "type": "string" }, "note": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": true, "anyOf": [ { "required": [ "developerId" ] }, { "required": [ "developer_id" ] } ] } } } } } }, "/api/partner-portal/statements": { "get": { "summary": "Read reseller statements", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Returns only member-accessible partner records. Historical customer identity, serials, commercial terms and conversations are private. Lists do not execute a payout, authorize a download or grant product ownership.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: statements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statements": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "query relationshipId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-portal/stores": { "get": { "summary": "Read authorized WooCommerce store connections", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires active owner/admin/technical membership for the returned store connections.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: connections.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js", "services/partnerWooCommerceService.js" ] } }, "/api/partner-portal/stores/{connectionId}/connect-link": { "post": { "summary": "Rotate the private store authorization link", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Requires eligible store access, an active relationship and a connectable state. Rotates authorization state and may authorize credential replacement. The returned connection contains a private connect link; do not log, publish or poll it.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js", "services/partnerWooCommerceService.js" ] } }, "/api/partner-portal/webhooks": { "get": { "summary": "Read reseller webhooks", "description": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface. Returns only member-accessible partner records. Historical customer identity, serials, commercial terms and conversations are private. Lists do not execute a payout, authorize a download or grant product ownership.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-portal" }, "parameters": [ { "name": "relationshipId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: webhooks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in account and eligible reseller membership; relationship and partner ownership apply. This is an account-session API, not the external partner API-key interface.", "x-request-fields": [ "query relationshipId: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerPortalRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner-referrals/{code}": { "get": { "summary": "Resolve an eligible referral to its storefront/product.", "description": "Public, rate-limited; records visit activity except HEAD. A click is not proof of a sale. Records supported aggregate referral activity and redirects. A click is not a conversion or commission; do not use this as a health probe. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner-programs" }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "product", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "303": { "description": "303 redirect with supported referral context.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Eligible storefront/product redirect with scoped referral context." } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account permissions and resource ownership described below.", "x-request-fields": [ "query product: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed transport contract; inspect the redirect/response headers and operation-specific authorization.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerProgramReferralRoutes.js", "services/partnerProgramReferralService.js" ] } }, "/api/partner/v1/campaigns": { "get": { "summary": "List partner-readable campaigns.", "description": "Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. External seller payments remain outside SoundSync managed-checkout processing coverage.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner" }, "parameters": [], "responses": { "200": { "description": "Campaign list for the relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "start_at": { "type": [ "string", "null" ], "format": "date-time" }, "end_at": { "type": [ "string", "null" ], "format": "date-time" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "reseller_sku": { "type": "string" }, "approved_sale_price_cents": { "type": "integer", "minimum": 0 }, "commercial_model": { "type": "string" }, "license_cap": { "type": "integer" }, "issued_count": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "campaigns:read", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/campaigns/{campaignId}": { "get": { "summary": "Load one partner campaign.", "description": "Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. External seller payments remain outside SoundSync managed-checkout processing coverage.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner" }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign detail for the relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "start_at": { "type": [ "string", "null" ], "format": "date-time" }, "end_at": { "type": [ "string", "null" ], "format": "date-time" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "reseller_sku": { "type": "string" }, "approved_sale_price_cents": { "type": "integer", "minimum": 0 }, "commercial_model": { "type": "string" }, "license_cap": { "type": "integer" }, "issued_count": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "campaigns:read", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/deals": { "get": { "summary": "Scoped deal listing", "description": "Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. External seller payments remain outside SoundSync managed-checkout processing coverage.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: campaigns, deals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "start_at": { "type": [ "string", "null" ], "format": "date-time" }, "end_at": { "type": [ "string", "null" ], "format": "date-time" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "reseller_sku": { "type": "string" }, "approved_sale_price_cents": { "type": "integer", "minimum": 0 }, "commercial_model": { "type": "string" }, "license_cap": { "type": "integer" }, "issued_count": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "start_at": { "type": [ "string", "null" ], "format": "date-time" }, "end_at": { "type": [ "string", "null" ], "format": "date-time" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "reseller_sku": { "type": "string" }, "approved_sale_price_cents": { "type": "integer", "minimum": 0 }, "commercial_model": { "type": "string" }, "license_cap": { "type": "integer" }, "issued_count": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/deals/{dealId}": { "get": { "summary": "Scoped deal detail", "description": "Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. External seller payments remain outside SoundSync managed-checkout processing coverage.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "dealId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: campaign, deal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "start_at": { "type": [ "string", "null" ], "format": "date-time" }, "end_at": { "type": [ "string", "null" ], "format": "date-time" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "reseller_sku": { "type": "string" }, "approved_sale_price_cents": { "type": "integer", "minimum": 0 }, "commercial_model": { "type": "string" }, "license_cap": { "type": "integer" }, "issued_count": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true }, "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "start_at": { "type": [ "string", "null" ], "format": "date-time" }, "end_at": { "type": [ "string", "null" ], "format": "date-time" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "reseller_sku": { "type": "string" }, "approved_sale_price_cents": { "type": "integer", "minimum": 0 }, "commercial_model": { "type": "string" }, "license_cap": { "type": "integer" }, "issued_count": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/licenses/{serial}": { "get": { "summary": "Fetch partner-visible license status.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/reseller-partner" }, "parameters": [ { "name": "serial", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "license.", "content": { "application/json": { "schema": { "type": "object", "properties": { "license": { "type": "object", "properties": { "serial": { "type": "string" }, "status": { "type": "string" }, "revoked": { "type": "boolean" }, "product_id": { "type": "integer", "minimum": 1 }, "external_order_id": { "type": "string" }, "customer": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "partner API key", "licenses:read scope", "serial path parameter" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/licenses/{serial}/revoke": { "post": { "summary": "Revoke a partner-visible license/serial.", "description": "Side effects: Revokes partner-visible license according to partner service policy.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/reseller-partner" }, "parameters": [ { "name": "serial", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revocation payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "serial": { "type": "string" }, "external_order_id": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner/v1/orders": { "post": { "summary": "Create/fulfill an external partner order.", "description": "Side effects: Creates external order, serial/license fulfillment, audit log, webhook event order.fulfilled, notifications, and idempotency record.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/reseller-partner" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Successful idempotent replay or duplicate confirmation; inspect the linked operation contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "soundsync_order_id": { "type": "string" }, "external_order_id": { "type": "string" }, "relationship_id": { "type": "string" }, "source": { "type": "string" }, "financial_classification": { "type": "string" }, "soundsync_checkout_fee_cents": { "type": "integer", "minimum": 0 }, "reported_total_paid_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "verification_status": { "type": "string" }, "fulfillment_event_created": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "duplicate_external_order": { "type": "boolean" }, "customer": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "fulfillment_status": { "type": "string" }, "expected_payable_cents": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "201": { "description": "201 order fulfillment payload, or 200 idempotent replay/duplicate external order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "soundsync_order_id": { "type": "string" }, "external_order_id": { "type": "string" }, "relationship_id": { "type": "string" }, "source": { "type": "string" }, "financial_classification": { "type": "string" }, "soundsync_checkout_fee_cents": { "type": "integer", "minimum": 0 }, "reported_total_paid_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "verification_status": { "type": "string" }, "fulfillment_event_created": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "duplicate_external_order": { "type": "boolean" }, "customer": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "fulfillment_status": { "type": "string" }, "expected_payable_cents": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Partner relationship and orders:write or sales:write scope.", "x-request-fields": [ "header Idempotency-Key: string (required)", "external_order_id: string", "externalOrderId: string", "customer_email: string", "customerEmail: string", "purchased_at: string", "purchasedAt: string", "items: array (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://www.soundsync.dev/contracts/partner-api.schema.json", "title": "Partner external order", "type": "object", "properties": { "external_order_id": { "type": "string" }, "externalOrderId": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "customerEmail": { "type": "string", "format": "email" }, "purchased_at": { "type": "string", "format": "date-time" }, "purchasedAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "reseller_sku": { "type": "string", "minLength": 1 }, "resellerSku": { "type": "string", "minLength": 1 }, "sku": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "default": 1 }, "unit_reported_price_cents": { "type": "integer", "minimum": 0 } }, "anyOf": [ { "required": [ "product_id" ] }, { "required": [ "productId" ] }, { "required": [ "reseller_sku" ] }, { "required": [ "resellerSku" ] }, { "required": [ "sku" ] } ] } } }, "allOf": [ { "anyOf": [ { "required": [ "external_order_id" ] }, { "required": [ "externalOrderId" ] } ] }, { "anyOf": [ { "required": [ "customer_email" ] }, { "required": [ "customerEmail" ] } ] }, { "anyOf": [ { "required": [ "purchased_at" ] }, { "required": [ "purchasedAt" ] } ] } ], "required": [ "items" ], "additionalProperties": true } } } } } }, "/api/partner/v1/orders/{externalOrderId}": { "get": { "summary": "Look up an external partner order by partner external ID.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/reseller-partner" }, "parameters": [ { "name": "externalOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order fulfillment payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "soundsync_order_id": { "type": "string" }, "external_order_id": { "type": "string" }, "relationship_id": { "type": "string" }, "source": { "type": "string" }, "financial_classification": { "type": "string" }, "soundsync_checkout_fee_cents": { "type": "integer", "minimum": 0 }, "reported_total_paid_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "verification_status": { "type": "string" }, "fulfillment_event_created": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "duplicate_external_order": { "type": "boolean" }, "customer": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "fulfillment_status": { "type": "string" }, "expected_payable_cents": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "partner API key", "orders:read scope" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/orders/{externalOrderId}/refund": { "post": { "summary": "Partner-facing external-order refund/reversal route.", "description": "Side effects: Applies partner refund/revoke behavior and logs API request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/orders" }, "parameters": [ { "name": "externalOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refund/revocation response for partner-visible fulfillment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "external_order_id": { "type": "string" }, "idempotent_replay": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Use the authentication and resource scope specified for this operation.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner/v1/orders/{externalOrderId}/revoke": { "post": { "summary": "Revoke access for an external order.", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner" }, "parameters": [ { "name": "externalOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revocation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "external_order_id": { "type": "string" }, "idempotent_replay": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "licenses:revoke", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner/v1/products": { "get": { "summary": "List products assigned to the authenticated partner relationship.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/reseller-partner" }, "parameters": [], "responses": { "200": { "description": "products[].", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "soundsync_sku": { "type": [ "string", "null" ] }, "product_id": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "developer_id": { "type": "integer", "minimum": 1 }, "short_description": { "type": "string" }, "description": { "type": "string" }, "currency": { "type": "string" }, "authorized": { "type": "boolean" }, "license_fulfillment": { "type": "string" }, "msrp_cents": { "type": [ "integer", "null" ], "minimum": 0 }, "suggested_sale_price_cents": { "type": [ "integer", "null" ], "minimum": 0 } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Partner relationship and products:read scope.", "x-request-fields": [ "Authorization partner API key", "products:read scope" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/products/{sku}": { "get": { "summary": "Fetch one partner-visible product by SKU.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/reseller-partner" }, "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "soundsync_sku": { "type": [ "string", "null" ] }, "product_id": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "developer_id": { "type": "integer", "minimum": 1 }, "short_description": { "type": "string" }, "description": { "type": "string" }, "currency": { "type": "string" }, "authorized": { "type": "boolean" }, "license_fulfillment": { "type": "string" }, "msrp_cents": { "type": [ "integer", "null" ], "minimum": 0 }, "suggested_sale_price_cents": { "type": [ "integer", "null" ], "minimum": 0 } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "partner API key", "products:read scope", "sku path parameter" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/products/{sku}/assets": { "get": { "summary": "Load partner-visible product asset metadata.", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner" }, "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Assets/download metadata authorized for the partner relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "soundsync_sku": { "type": [ "string", "null" ] }, "product_id": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "developer_id": { "type": "integer", "minimum": 1 }, "short_description": { "type": "string" }, "description": { "type": "string" }, "currency": { "type": "string" }, "authorized": { "type": "boolean" }, "license_fulfillment": { "type": "string" }, "msrp_cents": { "type": [ "integer", "null" ], "minimum": 0 }, "suggested_sale_price_cents": { "type": [ "integer", "null" ], "minimum": 0 } }, "additionalProperties": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "url": { "type": "string" }, "mime_type": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "products:read", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/sales": { "post": { "summary": "External order creation using the orders/sales contract", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Successful idempotent replay or duplicate confirmation; inspect the linked operation contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "soundsync_order_id": { "type": "string" }, "external_order_id": { "type": "string" }, "relationship_id": { "type": "string" }, "source": { "type": "string" }, "financial_classification": { "type": "string" }, "soundsync_checkout_fee_cents": { "type": "integer", "minimum": 0 }, "reported_total_paid_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "verification_status": { "type": "string" }, "fulfillment_event_created": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "duplicate_external_order": { "type": "boolean" }, "customer": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "fulfillment_status": { "type": "string" }, "expected_payable_cents": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "201": { "description": "HTTP 201: success, soundsync_order_id, external_order_id, relationship_id, source, financial_classification, soundsync_checkout_fee_cents, reported_total_paid_cents, currency, verification_status, fulfillment_event_created, idempotent_replay, duplicate_external_order, customer, items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "soundsync_order_id": { "type": "string" }, "external_order_id": { "type": "string" }, "relationship_id": { "type": "string" }, "source": { "type": "string" }, "financial_classification": { "type": "string" }, "soundsync_checkout_fee_cents": { "type": "integer", "minimum": 0 }, "reported_total_paid_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "verification_status": { "type": "string" }, "fulfillment_event_created": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "duplicate_external_order": { "type": "boolean" }, "customer": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "fulfillment_status": { "type": "string" }, "expected_payable_cents": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "header Idempotency-Key: string (required)", "external_order_id: string", "externalOrderId: string", "customer_email: string", "customerEmail: string", "purchased_at: string", "purchasedAt: string", "items: array (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://www.soundsync.dev/contracts/partner-api.schema.json", "title": "Partner external order", "type": "object", "properties": { "external_order_id": { "type": "string" }, "externalOrderId": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "customerEmail": { "type": "string", "format": "email" }, "purchased_at": { "type": "string", "format": "date-time" }, "purchasedAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "reseller_sku": { "type": "string", "minLength": 1 }, "resellerSku": { "type": "string", "minLength": 1 }, "sku": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "default": 1 }, "unit_reported_price_cents": { "type": "integer", "minimum": 0 } }, "anyOf": [ { "required": [ "product_id" ] }, { "required": [ "productId" ] }, { "required": [ "reseller_sku" ] }, { "required": [ "resellerSku" ] }, { "required": [ "sku" ] } ] } } }, "allOf": [ { "anyOf": [ { "required": [ "external_order_id" ] }, { "required": [ "externalOrderId" ] } ] }, { "anyOf": [ { "required": [ "customer_email" ] }, { "required": [ "customerEmail" ] } ] }, { "anyOf": [ { "required": [ "purchased_at" ] }, { "required": [ "purchasedAt" ] } ] } ], "required": [ "items" ], "additionalProperties": true } } } } } }, "/api/partner/v1/sales/{externalOrderId}": { "get": { "summary": "Lookup the reported sale", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "externalOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: success, soundsync_order_id, external_order_id, relationship_id, source, financial_classification, soundsync_checkout_fee_cents, reported_total_paid_cents, currency, verification_status, fulfillment_event_created, idempotent_replay, duplicate_external_order, customer, items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "soundsync_order_id": { "type": "string" }, "external_order_id": { "type": "string" }, "relationship_id": { "type": "string" }, "source": { "type": "string" }, "financial_classification": { "type": "string" }, "soundsync_checkout_fee_cents": { "type": "integer", "minimum": 0 }, "reported_total_paid_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "verification_status": { "type": "string" }, "fulfillment_event_created": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "duplicate_external_order": { "type": "boolean" }, "customer": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "product_name": { "type": "string" }, "fulfillment_status": { "type": "string" }, "expected_payable_cents": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/sales/{externalOrderId}/refund": { "post": { "summary": "Report the supported external refund", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "externalOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: status, code, external_order_id, idempotent_replay.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "external_order_id": { "type": "string" }, "idempotent_replay": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner/v1/sales/{externalOrderId}/revoke": { "post": { "summary": "Revoke under the approved external-access contract", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "externalOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: status, code, external_order_id, idempotent_replay.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "external_order_id": { "type": "string" }, "idempotent_replay": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner/v1/serial-pools": { "get": { "summary": "Scoped pool inventory; serial_pools:read", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "product_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "HTTP 200: serial_pools, pools.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serial_pools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" } }, "additionalProperties": true } }, "pools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query product_id: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/serial-pools/{poolId}": { "get": { "summary": "Scoped pool detail; serial_pools:read", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "poolId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: serial_pool, pool, items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serial_pool": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" } }, "additionalProperties": true }, "pool": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" } }, "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "serial_code": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/webhook-events": { "get": { "summary": "List partner webhook delivery attempts/events.", "description": "Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. External seller payments remain outside SoundSync managed-checkout processing coverage. Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/webhooks" }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "description": "" } ], "responses": { "200": { "description": "events[] with type/event_id/status/attempt_count/next_attempt_at/last_status_code/last_error/response_preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "type": { "type": "string" }, "endpoint": { "type": "string" }, "method": { "type": "string" }, "request_id": { "type": [ "string", "null" ] }, "idempotency_key": { "type": [ "string", "null" ] }, "external_order_id": { "type": [ "string", "null" ] }, "status_code": { "type": "integer" }, "success": { "type": "boolean" }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "request_summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "response_summary": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "subscription_id": { "type": [ "integer", "null" ] }, "type": { "type": "string" }, "event_id": { "type": "string" }, "status": { "type": "string" }, "attempt_count": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_status_code": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "response_preview": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] } }, "/api/partner/v1/webhooks": { "get": { "summary": "List partner webhook subscriptions.", "description": "Relationship-scoped partner key and operation-specific campaigns/webhooks read or write scope are required. External seller payments remain outside SoundSync managed-checkout processing coverage. Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/webhooks" }, "parameters": [], "responses": { "200": { "description": "webhooks[].", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] }, "post": { "summary": "Create a partner webhook subscription.", "description": "Returns private signing material inside webhook.secret, not a top-level secret. Only url is required: omitted events defaults to order.fulfilled, order.refunded, license.revoked and webhook.test. An explicit event list must retain at least one supported event after normalization. Use public HTTPS without credentials or a nonstandard port. Fulfillment availability and webhook-write scope are required; do not publish a live secret. Side effects: Stores webhook subscription and generated signing secret. Secret is shown once.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/webhooks" }, "parameters": [], "responses": { "201": { "description": "201 webhook plus one-time signing secret.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "secret": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "url: string (required)", "events: array", "description: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.fulfilled", "order.refunded", "license.revoked", "relationship.requested", "relationship.updated", "webhook.test" ] } }, "description": { "type": "string" } }, "required": [ "url" ], "additionalProperties": true } } } } } }, "/api/partner/v1/webhooks/{webhookId}": { "delete": { "summary": "Disable a partner webhook subscription.", "description": "Disables the subscription rather than implying physical erasure of webhook delivery/audit history. Side effects: Marks subscription disabled.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/webhooks" }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disabled webhook response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ] }, "patch": { "summary": "Update partner webhook subscription status/events/url/description or rotate secret when requested.", "description": "Side effects: May rotate the webhook secret.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/webhooks" }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "webhook; includes secret only when rotation was requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "properties": {}, "additionalProperties": true }, "secret": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "url: string", "events: array", "description: string", "rotate_secret: boolean", "status: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "rotate_secret": { "type": "boolean" }, "status": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner/v1/webhooks/{webhookId}/test": { "post": { "summary": "Send a test event through a specific partner webhook.", "description": "Can update the selected webhook status and queues a synthetic webhook.test event. Queue acceptance is not successful delivery.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/partner" }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test event result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "event": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "relationship_id": { "type": "integer", "minimum": 1 }, "partner_id": { "type": "integer", "minimum": 1 }, "developer_id": { "type": "integer", "minimum": 1 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "webhooks:write", "x-request-fields": [ "status: string", "message: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/partner/v1/webhooks/test": { "post": { "summary": "Queue a partner webhook.test delivery.", "description": "Side effects: Queues webhook.test delivery.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/webhooks" }, "parameters": [], "responses": { "200": { "description": "success true and event { type webhook.test, id, relationship_id, partner_id, developer_id, created_at }.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "event": { "type": "object", "properties": { "type": { "const": "webhook.test" }, "id": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Relationship-scoped partner API key", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "message: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "PartnerApiKey": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/partnerExternalApiRoutes.js", "services/partnerHubService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/plugin-connections/event": { "post": { "summary": "Record product UI telemetry using the compatibility alias", "description": "Authentication is read from JSON body, not a developer/customer Bearer token. Supply standard product key/secret or the matching generated native publicClient/app/product identity. Canonical event types: opened, ui_click, webview_opened, webview_click. click/button_click normalize to ui_click; plugin_opened to opened; webview_clicked to webview_click; unknown types also become ui_click. Status and metadata are caller-reported, not customer authorization. Verifies/refreshes product connection history, records an event and attempts an engagement signal. 202 recorded:false means no event row was returned, not a licensing grant. No idempotency guarantee; retries can duplicate engagement. Never include personal data, serials or credentials in metadata. /event is a compatibility alias.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/plugin-telemetry" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: ok, recorded, event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "recorded": { "type": "boolean" }, "event": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": true } } } }, "202": { "description": "The request completed but no event row was returned: recorded is false. This is not an idempotent replay or a customer license grant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "recorded": { "type": "boolean" }, "event": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired credentials or sign-in challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "JSON body credential check. Headers are not used for this endpoint.", "x-access-scope": "Product/app binding; standard key/secret or generated native public-client identity. No customer licensing authority.", "x-request-fields": [ "productId: integer", "product_id: integer", "appId: string", "app_id: string", "pluginKey: string", "plugin_key: string", "pluginSecret: string", "plugin_secret: string", "appKey: string", "app_key: string", "appSecret: string", "app_secret: string", "publicClient: hise-native | juce-native", "public_client: hise-native | juce-native", "pluginVersion: string", "plugin_version: string", "version: string", "environment: string", "env: string", "eventKind: string", "event_kind: string", "type: string", "action: string", "element: string", "screen: string", "status: string", "metadata: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/pluginConnectionRoutes.js", "controllers/pluginConnectionController.js", "services/pluginConnectionVerificationService.js", "services/betaPlatformToolsService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "app_id": { "type": "string" }, "pluginKey": { "type": "string" }, "plugin_key": { "type": "string" }, "pluginSecret": { "type": "string" }, "plugin_secret": { "type": "string" }, "appKey": { "type": "string" }, "app_key": { "type": "string" }, "appSecret": { "type": "string" }, "app_secret": { "type": "string" }, "publicClient": { "enum": [ "hise-native", "juce-native" ] }, "public_client": { "enum": [ "hise-native", "juce-native" ] }, "pluginVersion": { "type": "string" }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "environment": { "type": "string" }, "env": { "type": "string" }, "eventKind": { "type": "string" }, "event_kind": { "type": "string" }, "type": { "type": "string" }, "action": { "type": "string" }, "element": { "type": "string" }, "screen": { "type": "string" }, "status": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true, "allOf": [ { "anyOf": [ { "required": [ "productId" ] }, { "required": [ "product_id" ] } ] }, { "anyOf": [ { "required": [ "appId" ] }, { "required": [ "app_id" ] } ] }, { "anyOf": [ { "required": [ "publicClient" ] }, { "required": [ "public_client" ] }, { "allOf": [ { "anyOf": [ { "required": [ "pluginKey" ] }, { "required": [ "plugin_key" ] }, { "required": [ "appKey" ] }, { "required": [ "app_key" ] } ] }, { "anyOf": [ { "required": [ "pluginSecret" ] }, { "required": [ "plugin_secret" ] }, { "required": [ "appSecret" ] }, { "required": [ "app_secret" ] } ] } ] } ] } ] } } } } } }, "/api/plugin-connections/events": { "post": { "summary": "Record product UI telemetry", "description": "Authentication is read from JSON body, not a developer/customer Bearer token. Supply standard product key/secret or the matching generated native publicClient/app/product identity. Canonical event types: opened, ui_click, webview_opened, webview_click. click/button_click normalize to ui_click; plugin_opened to opened; webview_clicked to webview_click; unknown types also become ui_click. Status and metadata are caller-reported, not customer authorization. Verifies/refreshes product connection history, records an event and attempts an engagement signal. 202 recorded:false means no event row was returned, not a licensing grant. No idempotency guarantee; retries can duplicate engagement. Never include personal data, serials or credentials in metadata. /event is a compatibility alias.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/plugin-telemetry" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: ok, recorded, event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "recorded": { "type": "boolean" }, "event": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": true } } } }, "202": { "description": "The request completed but no event row was returned: recorded is false. This is not an idempotent replay or a customer license grant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "recorded": { "type": "boolean" }, "event": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired credentials or sign-in challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Access, identity, or product eligibility was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "JSON body credential check. Headers are not used for this endpoint.", "x-access-scope": "Product/app binding; standard key/secret or generated native public-client identity. No customer licensing authority.", "x-request-fields": [ "productId: integer", "product_id: integer", "appId: string", "app_id: string", "pluginKey: string", "plugin_key: string", "pluginSecret: string", "plugin_secret: string", "appKey: string", "app_key: string", "appSecret: string", "app_secret: string", "publicClient: hise-native | juce-native", "public_client: hise-native | juce-native", "pluginVersion: string", "plugin_version: string", "version: string", "environment: string", "env: string", "eventKind: string", "event_kind: string", "type: string", "action: string", "element: string", "screen: string", "status: string", "metadata: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/pluginConnectionRoutes.js", "controllers/pluginConnectionController.js", "services/pluginConnectionVerificationService.js", "services/betaPlatformToolsService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "app_id": { "type": "string" }, "pluginKey": { "type": "string" }, "plugin_key": { "type": "string" }, "pluginSecret": { "type": "string" }, "plugin_secret": { "type": "string" }, "appKey": { "type": "string" }, "app_key": { "type": "string" }, "appSecret": { "type": "string" }, "app_secret": { "type": "string" }, "publicClient": { "enum": [ "hise-native", "juce-native" ] }, "public_client": { "enum": [ "hise-native", "juce-native" ] }, "pluginVersion": { "type": "string" }, "plugin_version": { "type": "string" }, "version": { "type": "string" }, "environment": { "type": "string" }, "env": { "type": "string" }, "eventKind": { "type": "string" }, "event_kind": { "type": "string" }, "type": { "type": "string" }, "action": { "type": "string" }, "element": { "type": "string" }, "screen": { "type": "string" }, "status": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true, "allOf": [ { "anyOf": [ { "required": [ "productId" ] }, { "required": [ "product_id" ] } ] }, { "anyOf": [ { "required": [ "appId" ] }, { "required": [ "app_id" ] } ] }, { "anyOf": [ { "required": [ "publicClient" ] }, { "required": [ "public_client" ] }, { "allOf": [ { "anyOf": [ { "required": [ "pluginKey" ] }, { "required": [ "plugin_key" ] }, { "required": [ "appKey" ] }, { "required": [ "app_key" ] } ] }, { "anyOf": [ { "required": [ "pluginSecret" ] }, { "required": [ "plugin_secret" ] }, { "required": [ "appSecret" ] }, { "required": [ "app_secret" ] } ] } ] } ] } ] } } } } } }, "/api/plugin-connections/verify": { "post": { "summary": "Verify the standard product credential tuple or supported native public-client app/product identity before customer activation testing.", "description": "This endpoint reads its JSON body rather than substituting licensing headers. The native public-client path does not require a distributed pluginSecret. Connectivity/product identification is not customer entitlement or audio unlock. Side effects: Updates credential last-used state, upserts plugin connection status, and records a plugin connection event.", "externalDocs": { "url": "https://www.soundsync.dev/docs/licensing" }, "parameters": [], "responses": { "200": { "description": "ok/connected, productId, credentialId, pluginVersion, environment, lastSeenAt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "JSON body credential check. Headers are not used for this endpoint.", "x-access-scope": "Product, app, credential, environment, and machine scoped.", "x-request-fields": [ "productId: integer (required)", "appId: string (required)", "pluginKey: string", "pluginSecret: string", "publicClient: hise-native | juce-native", "pluginVersion: string", "environment: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "controllers/pluginConnectionController.js", "services/pluginConnectionVerificationService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "appId": { "type": "string" }, "pluginKey": { "type": "string" }, "pluginSecret": { "type": "string" }, "publicClient": { "enum": [ "hise-native", "juce-native" ] }, "pluginVersion": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "productId", "appId" ], "additionalProperties": true } } } } } }, "/api/products": { "get": { "summary": "List products visible to this developer account", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: review the response schema below.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] }, "post": { "summary": "Create through the compatible product endpoint", "description": "Creates a draft. Prefer /drafts and focused section saves for new integrations. The legacy create response is a product object, not the /drafts wrapper.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: id, name, product_type, short_desc, long_desc, price, sale_price, is_draft, product_status, marketplace_status, marketplace_visible, feature_list, image_url, file_urls, files, capabilities, product_page_content, packageCredential, setup_status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "name: string (required)", "short_desc: string,null", "long_desc: string,null", "feature_list: array", "image_url: string,null", "product_page_content: object. Saved product presentation fields. Use the product media/specification guides; licensing rules have separate guards.", "product_type: plugin | instrument | expansion | sample_pack | midi_pack | drum_pack | preset_pack | construction_kit | bundle | subscription | course | digital_asset | player", "capabilities: object", "price: number,string,null", "sale_price: number,string,null", "is_free: boolean", "file_urls: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Saved product presentation fields. Use the product media/specification guides; licensing rules have separate guards." }, "product_type": { "type": "string", "enum": [ "plugin", "instrument", "expansion", "sample_pack", "midi_pack", "drum_pack", "preset_pack", "construction_kit", "bundle", "subscription", "course", "digital_asset", "player" ] }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_free": { "type": "boolean" }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } } }, "additionalProperties": true, "required": [ "name" ] } } } } } }, "/api/products/{id}": { "delete": { "summary": "Permanently delete an eligible archived product", "description": "Requires products.archive, an archived product and the exact confirmation DELETE followed by the product ID, for example DELETE 123. Financial, licensing, relationship or other retained dependencies can block deletion. This does not erase required purchase records.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: deleted, productId.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "productId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "confirmation: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js", "services/productPermanentDeletionService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string" } }, "required": [ "confirmation" ], "additionalProperties": true } } } } }, "get": { "summary": "Read an authorized product and its current statistics", "description": "Opening the product can ensure package credentials. This is not a public catalog call or a credential-free health probe.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: id, name, product_type, short_desc, long_desc, price, sale_price, is_draft, product_status, marketplace_status, marketplace_visible, feature_list, image_url, file_urls, files, capabilities, product_page_content, packageCredential, setup_status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] }, "put": { "summary": "Update through the compatible full product endpoint", "description": "Prefer focused details/type/commerce saves. Existing subscription shape and licensing-rule locks remain authoritative; sending a saved object does not bypass them.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: id, name, product_type, short_desc, long_desc, price, sale_price, is_draft, product_status, marketplace_status, marketplace_visible, feature_list, image_url, file_urls, files, capabilities, product_page_content, packageCredential, setup_status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "name: string", "short_desc: string,null", "long_desc: string,null", "feature_list: array", "image_url: string,null", "product_page_content: object. Saved product presentation fields. Use the product media/specification guides; licensing rules have separate guards.", "product_type: plugin | instrument | expansion | sample_pack | midi_pack | drum_pack | preset_pack | construction_kit | bundle | subscription | course | digital_asset | player", "capabilities: object", "price: number,string,null", "sale_price: number,string,null", "is_free: boolean", "file_urls: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Saved product presentation fields. Use the product media/specification guides; licensing rules have separate guards." }, "product_type": { "type": "string", "enum": [ "plugin", "instrument", "expansion", "sample_pack", "midi_pack", "drum_pack", "preset_pack", "construction_kit", "bundle", "subscription", "course", "digital_asset", "player" ] }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_free": { "type": "boolean" }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } } }, "additionalProperties": true } } } } } }, "/api/products/{id}/ai-drafts": { "get": { "summary": "Read saved product AI drafts", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: drafts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "drafts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "tool_type": { "type": "string" }, "generated_payload_json": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productSetupAiService.js" ] } }, "/api/products/{id}/ai-drafts/{draftId}/applied": { "post": { "summary": "Mark a reviewed AI draft applied", "description": "Updates the draft status. It does not itself apply suggestions to the product or publish content.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productSetupAiService.js" ] } }, "/api/products/{id}/ai-drafts/{draftId}/discard": { "post": { "summary": "Mark an AI draft discarded", "description": "Updates the draft status. It does not itself apply suggestions to the product or publish content.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: draft.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1 }, "status": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "discarded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productSetupAiService.js" ] } }, "/api/products/{id}/archive": { "post": { "summary": "Archive this product", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: id, name, product_type, short_desc, long_desc, price, sale_price, is_draft, product_status, marketplace_status, marketplace_visible, feature_list, image_url, file_urls, files, capabilities, product_page_content, packageCredential, setup_status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] } }, "/api/products/{id}/commerce": { "patch": { "summary": "Save regular and sale pricing", "description": "Unspecified fields remain unchanged. The after-discount paid checkout minimum is $9.99 before tax. Product aliases documented in setup guides remain accepted; type and recurring-model locks can reject a change.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product, setup_status, setupStatus.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setupStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "price: number,string,null", "sale_price: number,string,null", "is_free: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_free": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/products/{id}/deals": { "get": { "summary": "List scheduled product deals", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: productId, product_id, pricing, deals, upcoming, active, history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "product_id": { "type": "integer", "minimum": 1 }, "pricing": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "salePrice": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } }, "additionalProperties": true } }, "upcoming": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "salePrice": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } }, "additionalProperties": true } }, "active": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "salePrice": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } }, "additionalProperties": true }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "salePrice": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js", "services/productScheduledDealService.js" ] }, "post": { "summary": "Schedule a product deal", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: deal, product, pricing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "salePrice": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "pricing": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "title: string", "dealName: string", "salePrice: number (required)", "currency: string", "startsAt: string (required)", "endsAt: string (required)", "notes: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js", "services/productScheduledDealService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "dealName": { "type": "string" }, "salePrice": { "type": "number" }, "currency": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string" }, "notes": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true, "required": [ "salePrice", "startsAt", "endsAt" ] } } } } } }, "/api/products/{id}/deals/{dealId}": { "patch": { "summary": "Edit an eligible scheduled deal", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dealId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: deal, pricing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "salePrice": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } }, "additionalProperties": true }, "pricing": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "title: string", "dealName: string", "salePrice: number", "currency: string", "startsAt: string", "endsAt: string", "notes: string", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js", "services/productScheduledDealService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "dealName": { "type": "string" }, "salePrice": { "type": "number" }, "currency": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string" }, "notes": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } } } }, "/api/products/{id}/deals/{dealId}/cancel": { "post": { "summary": "Cancel a product deal", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dealId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: deal, canceled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deal": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "salePrice": { "type": "number" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } }, "additionalProperties": true }, "canceled": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js", "services/productScheduledDealService.js" ] } }, "/api/products/{id}/delivery-files": { "post": { "summary": "Attach product delivery-file metadata from the developer product setup flow.", "description": "Attaches one file; a nested file object is also accepted. href aliases url; size aliases size_gb and is measured in GB. Use completed managed uploads. External delivery URLs must go through Upload by Link; signed, tokenized and raw private-storage URLs are rejected. Side effects: May update delivery-file configuration for the product. Not safe for read-only screenshot capture.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/entitlements" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product setup response controlled by product setup service.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": "number" } }, "additionalProperties": true } }, "setupStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Developer-owned product setup.", "x-request-fields": [ "url: string (required)", "name: string", "size_gb: number" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/productCreationOnboardingService.js", "services/developerProductService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "size_gb": { "type": "number", "minimum": 0 } }, "required": [ "url" ], "additionalProperties": true } } } } } }, "/api/products/{id}/details": { "patch": { "summary": "Save product copy, media references and presentation", "description": "Unspecified fields remain unchanged. The after-discount paid checkout minimum is $9.99 before tax. Product aliases documented in setup guides remain accepted; type and recurring-model locks can reject a change.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product, setup_status, setupStatus.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setupStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "name: string", "short_desc: string,null", "long_desc: string,null", "feature_list: array", "image_url: string,null", "product_page_content: object. Saved product presentation fields. Use the product media/specification guides; licensing rules have separate guards." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Saved product presentation fields. Use the product media/specification guides; licensing rules have separate guards." } }, "additionalProperties": true } } } } } }, "/api/products/{id}/files": { "get": { "summary": "List private delivery-file metadata", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] }, "post": { "summary": "Attach a completed managed delivery file", "description": "Use managed, completed uploads. A raw external delivery URL must go through Upload by Link. URL signing is not a permanent public download grant.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: product, files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "url: string (required)", "name: string", "size_gb: number" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "size_gb": { "type": "number" } }, "required": [ "url" ], "additionalProperties": true } } } } } }, "/api/products/{id}/files/{fileId}": { "delete": { "summary": "Detach a delivery file from the product", "description": "Detachment changes customer delivery. It is not a refund or a guarantee of physical storage deletion.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: detached, detached_index, files, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detached": { "type": "boolean" }, "detached_index": { "type": "integer" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] }, "patch": { "summary": "Rename delivery metadata or correct its reported size", "description": "fileId uses the current file_N identifier; it is not a storage key. Reload file metadata after insertions or removals.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: file, files, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "name: string", "size_gb: number" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "size_gb": { "type": "number" } }, "additionalProperties": true } } } } } }, "/api/products/{id}/files/{fileId}/download": { "get": { "summary": "Authorized developer file download", "description": "Developer-authorized private file preview/download metadata, not a public URL or customer entitlement grant.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: url, expiresIn.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expiresIn": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/productCreationOnboardingService.js", "services/developerProductService.js" ] } }, "/api/products/{id}/files/direct-uploads": { "post": { "summary": "Start or resume a direct upload", "description": "Use returned upload instructions. Local multipart resume requires reselecting the identical file within the returned deadline; the browser cannot reopen it silently.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/uploads" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Job and signed upload instructions; follow the returned mode and part limits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "filename: string (required)", "sizeBytes: integer (required)", "mimeType: string", "multipart: boolean", "fileFingerprint: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 10000000000 }, "mimeType": { "type": "string" }, "multipart": { "type": "boolean" }, "fileFingerprint": { "type": "string", "pattern": "^v1:[a-f0-9]{64}$" } }, "required": [ "filename", "sizeBytes" ], "additionalProperties": true } } } } } }, "/api/products/{id}/files/direct-uploads/{jobId}": { "get": { "summary": "Resume an eligible multipart upload", "description": "Resume requires the same file/session under the returned deadline; an expired upload is not silently reattached.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: job, upload, processing, deduplicated, file, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js" ] } }, "/api/products/{id}/files/direct-uploads/{jobId}/complete": { "post": { "summary": "Verify and attach a stored upload", "description": "Completes only after object/session/size verification. Do not manually attach an unfinished storage key.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/uploads" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job and attachment result after stored-object/session checks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "sizeBytes: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sizeBytes": { "type": "integer" } }, "additionalProperties": true } } } } } }, "/api/products/{id}/files/direct-uploads/{jobId}/part": { "post": { "summary": "Prepare a part using JSON", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/uploads" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Temporary PUT instructions for the permitted part.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [ "partNumber: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 } }, "required": [ "partNumber" ], "additionalProperties": true } } } } } }, "/api/products/{id}/files/direct-uploads/{jobId}/parts/{partNumber}": { "post": { "summary": "Prepare the specified part", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/uploads" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "partNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Temporary PUT instructions for the permitted part.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Workspace permissions and product assignments are checked.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/products/{id}/files/upload-link": { "post": { "summary": "Prepare a permitted remote upload", "description": "Imports an authorized direct link into private storage. A pending job is not a deliverable file; protected/expired links need a fresh direct source.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "HTTP 202: job, upload, processing, deduplicated, file, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "url: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ], "additionalProperties": true } } } } } }, "/api/products/{id}/files/uploads": { "get": { "summary": "List current upload jobs", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js" ] }, "post": { "summary": "Upload a buffered local delivery file", "description": "Buffered upload limits are lower than direct multipart limits. Use direct upload for larger files.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: job, upload, processing, deduplicated, file, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/products/{id}/files/uploads/{jobId}": { "get": { "summary": "Read job state", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: job, upload, processing, deduplicated, file, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/products/{id}/files/uploads/{jobId}/cancel": { "post": { "summary": "Cancel the upload job", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: job, upload, processing, deduplicated, file, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/products/{id}/files/uploads/{jobId}/retry": { "post": { "summary": "Retry supported failed work", "description": "A remote retry may restart from the source; do not promise byte-level resume.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: job, upload, processing, deduplicated, file, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/products/{id}/files/uploads/chunk-sessions": { "post": { "summary": "Start a local chunk session", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "HTTP 201: upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "filename": { "type": "string" }, "totalSize": { "type": "integer" }, "totalChunks": { "type": "integer" }, "chunkSize": { "type": "integer" }, "maxChunkSize": { "type": "integer" }, "receivedBytes": { "type": "integer" }, "progress": { "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "filename: string (required)", "mimeType: string", "size: integer (required)", "totalChunks: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer" }, "totalChunks": { "type": "integer", "minimum": 1 } }, "required": [ "filename", "size", "totalChunks" ], "additionalProperties": true } } } } } }, "/api/products/{id}/files/uploads/chunk-sessions/{uploadId}/chunks": { "post": { "summary": "Upload a multipart chunk", "description": "Upload the chunk file under the chunk field. index is zero-based; validate returned completion rather than assuming arrival order.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "filename": { "type": "string" }, "totalSize": { "type": "integer" }, "totalChunks": { "type": "integer" }, "receivedBytes": { "type": "integer" }, "progress": { "type": "number" }, "complete": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "index: integer (required)", "chunk: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "chunk": { "type": "string", "format": "binary" } }, "required": [ "index", "chunk" ], "additionalProperties": true } } } } } }, "/api/products/{id}/files/uploads/chunk-sessions/{uploadId}/complete": { "post": { "summary": "Complete chunk assembly", "description": "Missing or mismatched chunks fail verification; processing can continue asynchronously after assembly.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: job, upload, processing, deduplicated, file, product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "sourceType": { "type": "string" }, "originalFilename": { "type": "string" }, "filename": { "type": "string" }, "storageKey": { "type": "string" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "attachedProductFileId": { "type": [ "string", "integer" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expectedSizeBytes": { "type": [ "integer", "null" ] }, "resumable": { "type": "boolean" }, "resumeExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "upload": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "partSize": { "type": "integer" }, "partNumber": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "expiresIn": { "type": "integer" } }, "additionalProperties": true }, "processing": { "type": "boolean" }, "deduplicated": { "type": "boolean" }, "file": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "key": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "services/productFileUploadJobService.js", "services/productFileMultipart.js" ] } }, "/api/products/{id}/pricing": { "get": { "summary": "Resolve the current regular and sale price", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: pricing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pricing": { "type": "object", "properties": { "regularPrice": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "finalPrice": { "type": "number" }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "activeDealId": { "type": [ "integer", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js", "services/productPricingService.js" ] } }, "/api/products/{id}/publish": { "post": { "summary": "Publish a ready product and choose public listing", "description": "Requires the current owner/admin authorization and complete setup. Can provision credentials and schedule marketplace artwork. Listing, generated artwork, placement approval and guaranteed discovery are different outcomes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product, setup_status, setupStatus.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setupStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "list_publicly: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "list_publicly": { "type": "boolean" } }, "additionalProperties": true } } } } } }, "/api/products/{id}/published-subscription": { "patch": { "summary": "Update a published subscription product atomically", "description": "Only an already published linked subscription product is eligible. This groups supported section changes in one transaction; it does not change the subscription ownership model or transfer provider billing authority. Changing monthly/yearly cadence with active, trialing, past_due or unpaid standalone or linked bundle contracts returns 409 SUBSCRIPTION_BILLING_INTERVAL_LOCKED. Keep existing contracts on their cadence and create a separate offer for the new interval.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product, setup_status, setupStatus.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setupStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "details: object", "type: object", "commerce: object", "subscriptionSettings: object", "publish: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "SUBSCRIPTION_BILLING_INTERVAL_LOCKED" ], "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js", "services/subscriptionPlanSafetyService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "details": { "type": "object", "properties": { "name": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Saved product presentation fields. Use the product media/specification guides; licensing rules have separate guards." } }, "additionalProperties": true }, "type": { "type": "object", "properties": { "product_type": { "type": "string", "enum": [ "plugin", "instrument", "expansion", "sample_pack", "midi_pack", "drum_pack", "preset_pack", "construction_kit", "bundle", "subscription", "course", "digital_asset", "player" ] }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "commerce": { "type": "object", "properties": { "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_free": { "type": "boolean" } }, "additionalProperties": true }, "subscriptionSettings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "billingInterval": { "type": "string" }, "trialDays": { "type": "integer" }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" } }, "additionalProperties": true }, "publish": { "type": "object", "properties": { "list_publicly": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } } } }, "/api/products/{id}/restore": { "post": { "summary": "Restore this archived product", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: id, name, product_type, short_desc, long_desc, price, sale_price, is_draft, product_status, marketplace_status, marketplace_visible, feature_list, image_url, file_urls, files, capabilities, product_page_content, packageCredential, setup_status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] } }, "/api/products/{id}/setup-status": { "get": { "summary": "Inspect incomplete product setup requirements", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product, setup_status, setupStatus.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setupStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] } }, "/api/products/{id}/stats": { "get": { "summary": "Read statistics for one authorized product", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: stats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "total_orders": { "type": "integer" }, "total_customers": { "type": "integer" }, "total_entitlements": { "type": "integer" }, "active_entitlements": { "type": "integer" }, "file_count": { "type": "integer" }, "gross_sales_amount_cents": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] } }, "/api/products/{id}/type": { "patch": { "summary": "Save product type and compatible capabilities", "description": "Unspecified fields remain unchanged. The after-discount paid checkout minimum is $9.99 before tax. Product aliases documented in setup guides remain accepted; type and recurring-model locks can reject a change.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product, setup_status, setupStatus.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setupStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "product_type: plugin | instrument | expansion | sample_pack | midi_pack | drum_pack | preset_pack | construction_kit | bundle | subscription | course | digital_asset | player", "capabilities: object" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_type": { "type": "string", "enum": [ "plugin", "instrument", "expansion", "sample_pack", "midi_pack", "drum_pack", "preset_pack", "construction_kit", "bundle", "subscription", "course", "digital_asset", "player" ] }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } } } }, "/api/products/{id}/unpublish": { "post": { "summary": "Stop publication without erasing purchase history", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: product, setup_status, setupStatus.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setupStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/products/ai/faq-support": { "post": { "summary": "Draft FAQ and support answers", "description": "Requires enabled provider configuration and authorized product context. Review suggestions before saving. Generation is not publication, consent, compatibility verification or a performance guarantee.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string" }, "persistenceWarning": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "productId: integer", "currentProduct: object", "notes: string", "instructions: string", "referenceUrl: string", "referenceUrls: array", "videoLinks: array", "audioLinks: array", "downloadLinks: array", "mediaNotes: string", "preserveFilled: boolean", "targetCustomer: string", "tone: string", "imageStyle: string", "imagePrompt: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productSetupAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "currentProduct": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "referenceUrl": { "type": "string" }, "referenceUrls": { "type": "array", "items": { "type": "string" } }, "videoLinks": { "type": "array", "items": { "type": "string" } }, "audioLinks": { "type": "array", "items": { "type": "string" } }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "mediaNotes": { "type": "string" }, "preserveFilled": { "type": "boolean" }, "targetCustomer": { "type": "string" }, "tone": { "type": "string" }, "imageStyle": { "type": "string" }, "imagePrompt": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/products/ai/page-optimizer": { "post": { "summary": "Suggest product-page improvements", "description": "Requires enabled provider configuration and authorized product context. Review suggestions before saving. Generation is not publication, consent, compatibility verification or a performance guarantee.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string" }, "persistenceWarning": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "productId: integer", "currentProduct: object", "notes: string", "instructions: string", "referenceUrl: string", "referenceUrls: array", "videoLinks: array", "audioLinks: array", "downloadLinks: array", "mediaNotes: string", "preserveFilled: boolean", "targetCustomer: string", "tone: string", "imageStyle: string", "imagePrompt: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productSetupAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "currentProduct": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "referenceUrl": { "type": "string" }, "referenceUrls": { "type": "array", "items": { "type": "string" } }, "videoLinks": { "type": "array", "items": { "type": "string" } }, "audioLinks": { "type": "array", "items": { "type": "string" } }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "mediaNotes": { "type": "string" }, "preserveFilled": { "type": "boolean" }, "targetCustomer": { "type": "string" }, "tone": { "type": "string" }, "imageStyle": { "type": "string" }, "imagePrompt": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/products/ai/product-image": { "post": { "summary": "Generate draft product artwork", "description": "Requires enabled provider configuration and authorized product context. Review suggestions before saving. Generation is not publication, consent, compatibility verification or a performance guarantee.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string" }, "persistenceWarning": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "productId: integer", "currentProduct: object", "notes: string", "instructions: string", "referenceUrl: string", "referenceUrls: array", "videoLinks: array", "audioLinks: array", "downloadLinks: array", "mediaNotes: string", "preserveFilled: boolean", "targetCustomer: string", "tone: string", "imageStyle: string", "imagePrompt: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productSetupAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "currentProduct": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "referenceUrl": { "type": "string" }, "referenceUrls": { "type": "array", "items": { "type": "string" } }, "videoLinks": { "type": "array", "items": { "type": "string" } }, "audioLinks": { "type": "array", "items": { "type": "string" } }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "mediaNotes": { "type": "string" }, "preserveFilled": { "type": "boolean" }, "targetCustomer": { "type": "string" }, "tone": { "type": "string" }, "imageStyle": { "type": "string" }, "imagePrompt": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/products/ai/smart-info": { "post": { "summary": "Draft product information", "description": "Requires enabled provider configuration and authorized product context. Review suggestions before saving. Generation is not publication, consent, compatibility verification or a performance guarantee.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": [ "integer", "string", "null" ], "minLength": 1 }, "toolType": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "provider": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string" }, "persistenceWarning": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Request or operation limit reached; do not create duplicate financial work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "productId: integer", "currentProduct: object", "notes: string", "instructions: string", "referenceUrl: string", "referenceUrls: array", "videoLinks: array", "audioLinks: array", "downloadLinks: array", "mediaNotes: string", "preserveFilled: boolean", "targetCustomer: string", "tone: string", "imageStyle: string", "imagePrompt: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productSetupAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "currentProduct": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "notes": { "type": "string" }, "instructions": { "type": "string" }, "referenceUrl": { "type": "string" }, "referenceUrls": { "type": "array", "items": { "type": "string" } }, "videoLinks": { "type": "array", "items": { "type": "string" } }, "audioLinks": { "type": "array", "items": { "type": "string" } }, "downloadLinks": { "type": "array", "items": { "type": "string" } }, "mediaNotes": { "type": "string" }, "preserveFilled": { "type": "boolean" }, "targetCustomer": { "type": "string" }, "tone": { "type": "string" }, "imageStyle": { "type": "string" }, "imagePrompt": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/products/ai/upload-by-link/validate": { "post": { "summary": "Check whether a delivery source URL can be prepared", "description": "Send one URL alias. Safety checking does not import or attach a file. Start Upload by Link separately; private/local network sources are rejected.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: available, status, provider, message, draftOnly, developerId, userId.", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "status": { "type": "string" }, "provider": { "type": "string" }, "message": { "type": "string" }, "draftOnly": { "type": "boolean" }, "developerId": { "type": "integer", "minimum": 1 }, "userId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "url: string", "fileUrl: string", "referenceUrl: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "services/productSetupAiService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "fileUrl": { "type": "string" }, "referenceUrl": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/products/download/{code}": { "get": { "summary": "Resolve product download links by download code.", "description": "Legacy serial download listing requires the signed-in owning customer, a redeemed/unexpired serial and available download allowance; serial possession alone is insufficient.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/delivery-downloads" }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Authorized download links for the product/order context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/productCreationOnboardingService.js", "services/developerProductService.js" ] } }, "/api/products/download/{code}/{filename}": { "get": { "summary": "Download one product file by code and filename.", "description": "Only authorized product filenames are eligible. Requires signed-in owning customer; records the download before redirect.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/delivery-downloads" }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "filename", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Protected file response.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Short-lived authorized private download URL." } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed transport contract; inspect the redirect/response headers and operation-specific authorization.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/productCreationOnboardingService.js", "services/developerProductService.js" ] } }, "/api/products/drafts": { "post": { "summary": "Create a saved draft and inspect setup readiness", "description": "The draft path can use a placeholder name. No publication or paid access is implied. Package credential provisioning can occur; keep returned credential material private.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: product, setup_status, setupStatus.", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "product_type": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_draft": { "type": "boolean" }, "product_status": { "type": "string" }, "marketplace_status": { "type": "string" }, "marketplace_visible": { "type": "boolean" }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "kind": { "type": "string" }, "attached": { "type": "boolean" }, "size_gb": { "type": [ "number", "null" ] } }, "required": [ "id", "index", "name", "kind", "attached", "size_gb" ], "additionalProperties": true } }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "packageCredential": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "setup_status": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "setupStatus": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "name: string", "short_desc: string,null", "long_desc: string,null", "feature_list: array", "image_url: string,null", "product_page_content: object. Saved product presentation fields. Use the product media/specification guides; licensing rules have separate guards.", "product_type: plugin | instrument | expansion | sample_pack | midi_pack | drum_pack | preset_pack | construction_kit | bundle | subscription | course | digital_asset | player", "capabilities: object", "price: number,string,null", "sale_price: number,string,null", "is_free: boolean", "file_urls: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "short_desc": { "type": [ "string", "null" ] }, "long_desc": { "type": [ "string", "null" ] }, "feature_list": { "type": "array", "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ] }, "product_page_content": { "type": "object", "additionalProperties": true, "description": "Saved product presentation fields. Use the product media/specification guides; licensing rules have separate guards." }, "product_type": { "type": "string", "enum": [ "plugin", "instrument", "expansion", "sample_pack", "midi_pack", "drum_pack", "preset_pack", "construction_kit", "bundle", "subscription", "course", "digital_asset", "player" ] }, "capabilities": { "type": "object", "properties": { "requires_activation": { "type": "boolean" }, "supports_serials": { "type": "boolean" }, "supports_downloads": { "type": "boolean" }, "supports_expansions": { "type": "boolean" }, "is_publicly_listable": { "type": "boolean" }, "is_storefront_sellable": { "type": "boolean" } }, "additionalProperties": true }, "price": { "type": [ "number", "string", "null" ] }, "sale_price": { "type": [ "number", "string", "null" ] }, "is_free": { "type": "boolean" }, "file_urls": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size_gb": { "type": [ "number", "null" ] } }, "additionalProperties": true } } }, "additionalProperties": true } } } } } }, "/api/products/stats": { "get": { "summary": "Read authorized product statistics", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "total_orders": { "type": "integer" }, "total_customers": { "type": "integer" }, "total_entitlements": { "type": "integer" }, "active_entitlements": { "type": "integer" }, "file_count": { "type": "integer" }, "gross_sales_amount_cents": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ] } }, "/api/products/upload-file": { "post": { "summary": "Upload an image through the compatible image route", "description": "This is an image-upload response, not private product delivery. Check upload policy and use product media management for current workflows.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/products" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: url.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Authenticated account, effective developer workspace, applicable permissions and product ownership. Read the operation notes for legacy or owner-only restrictions.", "x-request-fields": [ "file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/productRoutes.js", "controllers/productController.js", "services/developerProductService.js", "services/productCreationOnboardingService.js" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/rent-to-own/checkout": { "post": { "summary": "Authenticated test checkout; production live requests rejected", "description": "Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: rentToOwnCheckout, productionExposureAllowed, url, checkoutUrl, checkoutSession, checkoutSessionRecord, planVersion, option.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rentToOwnCheckout": { "type": "boolean" }, "productionExposureAllowed": { "const": false }, "url": { "type": [ "string", "null" ] }, "checkoutUrl": { "type": [ "string", "null" ] }, "checkoutSession": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "checkoutSessionRecord": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "planVersion": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "option": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "eligible": { "type": "boolean" }, "enabled": { "type": "boolean" }, "ineligibilityReasons": { "type": "array", "items": { "type": "string" } }, "currency": { "type": "string" }, "cashPriceCents": { "type": "integer", "minimum": 0 }, "installmentAmountCents": { "type": "integer", "minimum": 0 }, "installmentCount": { "type": "integer" }, "totalContractCents": { "type": "integer", "minimum": 0 }, "roundingAdjustmentCents": { "type": "integer" }, "billingInterval": { "type": "string" }, "priceStrategy": { "type": "string" }, "promotionPolicy": { "type": "string" }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "termsUrl": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "productionExposureAllowed": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "productId: integer (required)", "metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.", "successUrl: string", "cancelUrl: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "successUrl": { "type": "string" }, "cancelUrl": { "type": "string" } }, "required": [ "productId" ], "additionalProperties": true } } } } } }, "/api/rent-to-own/customer/agreements": { "get": { "summary": "List agreements owned by the signed-in customer", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/rent-to-own" }, "parameters": [ { "name": "developerId", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: agreements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "customerUserId": { "type": [ "integer", "null" ] }, "customerId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": [ "string", "null" ] }, "planVersionId": { "type": "integer", "minimum": 1 }, "checkoutId": { "type": [ "integer", "null" ] }, "entitlementId": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "providerSubscriptionId": { "type": [ "string", "null" ] }, "environment": { "type": "string" }, "status": { "type": "string" }, "accessState": { "type": "string" }, "ownershipState": { "type": "string" }, "currency": { "type": "string" }, "cashPriceCents": { "type": "integer" }, "installmentAmountCents": { "type": "integer" }, "installmentCount": { "type": "integer" }, "totalContractCents": { "type": "integer" }, "paidInstallmentCount": { "type": "integer" }, "netPaidInstallmentCount": { "type": "integer" }, "paidAmountCents": { "type": "integer" }, "refundedAmountCents": { "type": "integer" }, "disputedAmountCents": { "type": "integer" }, "currentPeriodStart": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "nextPaymentAt": { "type": [ "string", "null" ], "format": "date-time" }, "failedPaymentGraceUntil": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "ownedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "installments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "installmentNumber": { "type": "integer" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amountDueCents": { "type": "integer" }, "amountPaidCents": { "type": "integer" }, "amountRefundedCents": { "type": "integer" }, "taxAmountCents": { "type": "integer" }, "discountAmountCents": { "type": "integer" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "disputedAt": { "type": [ "string", "null" ], "format": "date-time" }, "orderId": { "type": [ "integer", "null" ] } }, "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Same buyer-ownership checks as customer agreement detail.", "x-request-fields": [ "query developerId: integer", "query status: string", "query limit: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ] } }, "/api/rent-to-own/customer/agreements/{agreementId}": { "get": { "summary": "Read an agreement owned by the signed-in customer", "description": "Imported-contact ownership does not grant buyer access. A visible agreement is not authorization to charge again or alter its installment count.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/rent-to-own" }, "parameters": [ { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: agreement.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "customerUserId": { "type": [ "integer", "null" ] }, "customerId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": [ "string", "null" ] }, "planVersionId": { "type": "integer", "minimum": 1 }, "checkoutId": { "type": [ "integer", "null" ] }, "entitlementId": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "providerSubscriptionId": { "type": [ "string", "null" ] }, "environment": { "type": "string" }, "status": { "type": "string" }, "accessState": { "type": "string" }, "ownershipState": { "type": "string" }, "currency": { "type": "string" }, "cashPriceCents": { "type": "integer" }, "installmentAmountCents": { "type": "integer" }, "installmentCount": { "type": "integer" }, "totalContractCents": { "type": "integer" }, "paidInstallmentCount": { "type": "integer" }, "netPaidInstallmentCount": { "type": "integer" }, "paidAmountCents": { "type": "integer" }, "refundedAmountCents": { "type": "integer" }, "disputedAmountCents": { "type": "integer" }, "currentPeriodStart": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "nextPaymentAt": { "type": [ "string", "null" ], "format": "date-time" }, "failedPaymentGraceUntil": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "ownedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "installments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "installmentNumber": { "type": "integer" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amountDueCents": { "type": "integer" }, "amountPaidCents": { "type": "integer" }, "amountRefundedCents": { "type": "integer" }, "taxAmountCents": { "type": "integer" }, "discountAmountCents": { "type": "integer" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "disputedAt": { "type": [ "string", "null" ], "format": "date-time" }, "orderId": { "type": [ "integer", "null" ] } }, "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in customer account. A saved customer_user_id must match; only unbound legacy agreements can use the current verified account email.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ] } }, "/api/rent-to-own/customer/agreements/{agreementId}/cancel": { "post": { "summary": "Cancel a buyer agreement under its saved cancellation policy", "description": "Only reason is customer-editable. The saved agreement cancellationBehavior is authoritative, defaulting to access_until_period_end for legacy agreements. Body policy overrides are ignored. Repeated requests preserve local cancellation with unchanged:true. A pending provider step is retried with the same provider idempotency key; a recorded confirmed step is not sent again. Provider failure returns 502 rent_to_own_cancellation_pending with retryable:true and localCancellationSaved:true. Read metadata.providerCancellation.status; pending is not provider confirmation. Retry this same cancellation request, not a checkout or charge. There is no automatic retry timing promise. Completed/owned, refunded, disputed, revoked or ownership-revoked agreements return 409. Period-end cancellation preserves pending, past-due, grace and suspended lifecycle states, so existing expiry checks still run; it does not upgrade them to paid access. Live rent-to-own checkout remains unavailable; this does not enable new production installment sales.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/rent-to-own" }, "parameters": [ { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: agreement, immediate, unchanged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agreement": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "developerId": { "type": "integer", "minimum": 1 }, "customerUserId": { "type": [ "integer", "null" ] }, "customerId": { "type": "integer", "minimum": 1 }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": [ "string", "null" ] }, "planVersionId": { "type": "integer", "minimum": 1 }, "checkoutId": { "type": [ "integer", "null" ] }, "entitlementId": { "type": [ "integer", "null" ] }, "provider": { "type": "string" }, "providerSubscriptionId": { "type": [ "string", "null" ] }, "environment": { "type": "string" }, "status": { "type": "string" }, "accessState": { "type": "string" }, "ownershipState": { "type": "string" }, "currency": { "type": "string" }, "cashPriceCents": { "type": "integer" }, "installmentAmountCents": { "type": "integer" }, "installmentCount": { "type": "integer" }, "totalContractCents": { "type": "integer" }, "paidInstallmentCount": { "type": "integer" }, "netPaidInstallmentCount": { "type": "integer" }, "paidAmountCents": { "type": "integer" }, "refundedAmountCents": { "type": "integer" }, "disputedAmountCents": { "type": "integer" }, "currentPeriodStart": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "nextPaymentAt": { "type": [ "string", "null" ], "format": "date-time" }, "failedPaymentGraceUntil": { "type": [ "string", "null" ], "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "ownedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "installments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "installmentNumber": { "type": "integer" }, "status": { "type": "string" }, "currency": { "type": "string" }, "amountDueCents": { "type": "integer" }, "amountPaidCents": { "type": "integer" }, "amountRefundedCents": { "type": "integer" }, "taxAmountCents": { "type": "integer" }, "discountAmountCents": { "type": "integer" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "disputedAt": { "type": [ "string", "null" ], "format": "date-time" }, "orderId": { "type": [ "integer", "null" ] } }, "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "immediate": { "type": "boolean" }, "unchanged": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Signed-in buyer only; authenticated identity and route agreement ID cannot be supplied in the body.", "x-request-fields": [ "reason: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "rent_to_own_cancellation_pending" ], "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } } } }, "/api/rent-to-own/products/{productId}/option": { "get": { "summary": "Public product option", "description": "Rent-to-own installment checkout is a separate test-only path; live checkout is rejected with rent_to_own_live_checkout_unavailable. This is not the supported keep_products subscription-bundle ownership model. No production availability or financial flag change is implied.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: option.", "content": { "application/json": { "schema": { "type": "object", "properties": { "option": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "eligible": { "type": "boolean" }, "enabled": { "type": "boolean" }, "ineligibilityReasons": { "type": "array", "items": { "type": "string" } }, "currency": { "type": "string" }, "cashPriceCents": { "type": "integer", "minimum": 0 }, "installmentAmountCents": { "type": "integer", "minimum": 0 }, "installmentCount": { "type": "integer" }, "totalContractCents": { "type": "integer", "minimum": 0 }, "roundingAdjustmentCents": { "type": "integer" }, "billingInterval": { "type": "string" }, "priceStrategy": { "type": "string" }, "promotionPolicy": { "type": "string" }, "failedPaymentGraceDays": { "type": "integer" }, "cancellationBehavior": { "type": "string" }, "termsUrl": { "type": "string" }, "displayTitle": { "type": "string" }, "displayDisclaimer": { "type": "string" }, "productionExposureAllowed": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/developerRentToOwnRoutes.js", "routes/rentToOwnRoutes.js", "services/rentToOwnService.js" ] } }, "/api/serials/{id}": { "patch": { "summary": "Update a serial record.", "description": "Requires serials.manage, product ownership and assigned product scope. With no action, updates only an unlinked, unredeemed serial contact email. Changing a linked or redeemed customer identity returns 409 SERIAL_CUSTOMER_IDENTITY_LOCKED; use current customer information controls. reassign clears revocation; it does not redeem or transfer access.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated serial record or status summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "customer_email": { "type": [ "string", "null" ] }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_count": { "type": "integer" }, "status": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "serials.manage, the serial product owned by the effective developer workspace, and assigned product access. Foreign serial IDs are not available.", "x-request-fields": [ "action: revoke | reassign", "customer_email: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "SERIAL_CUSTOMER_IDENTITY_LOCKED" ], "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js", "services/legacySerialMutationService.js" ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "revoke", "reassign" ] }, "customer_email": { "type": "string", "format": "email" } }, "additionalProperties": true, "anyOf": [ { "required": [ "action" ] }, { "required": [ "customer_email" ] } ] } } } } } }, "/api/serials/available": { "get": { "summary": "List available serials for the signed-in developer.", "description": "Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Grouped regular and promotion serial inventory by product or batch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "regular": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "customer_email": { "type": [ "string", "null" ] }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_count": { "type": "integer" }, "status": { "type": "string" } }, "additionalProperties": true } } }, "promos": { "type": "object", "additionalProperties": { "type": "object", "properties": { "product_name": { "type": "string" }, "promo_price": { "type": "number" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "customer_email": { "type": [ "string", "null" ] }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_count": { "type": "integer" }, "status": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query search: string", "query dateRange: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/customers-list": { "get": { "summary": "List customers for serial assignment and filtering.", "description": "Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "Developer-scoped customer list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "customer_email": { "type": "string", "format": "email" }, "first_redemption": { "type": [ "string", "null" ], "format": "date-time" }, "latest_redemption": { "type": [ "string", "null" ], "format": "date-time" }, "product_count": { "type": "integer" }, "status": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/demo-csv": { "get": { "summary": "Download a demo CSV template for serial import.", "description": "Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "CSV template.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/download/{serialId}": { "get": { "summary": "Serve an authorized serial-linked download.", "description": "Requires serial/download context and signed-in owning customer. Only permitted managed files are signed.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [ { "name": "serialId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" }, { "name": "file", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" } ], "responses": { "302": { "description": "Authorized redirect to short-lived signed R2 delivery.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Short-lived authorized private download URL." } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT + private token query parameter", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query token: string (required)", "query file: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [], "LegacyDownloadQueryToken": [] } ], "x-contract-coverage": "Reviewed transport contract; inspect the redirect/response headers and operation-specific authorization.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/download/confirm": { "post": { "summary": "Confirm successful serial download.", "description": "Deprecated compatibility helper. Missing or foreign ownership is denied before reading counters or changing activity. Use entitlement delivery for new clients.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "200 JSON { success: true } after recording download activity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The customer account's owned, redeemed, non-revoked serial and its current product files.", "x-request-fields": [ "serial_id: integer (required)", "file_url: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serial_id": { "type": "integer", "minimum": 1 }, "file_url": { "type": "string" } }, "required": [ "serial_id", "file_url" ], "additionalProperties": true } } } } } }, "/api/serials/download/increment": { "post": { "summary": "Check the legacy serial download allowance.", "description": "Deprecated compatibility helper. Missing or foreign ownership is denied before reading counters or changing activity. Use entitlement delivery for new clients.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "200 JSON { allowed: boolean }. This check does not increment the counter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The customer account's owned, redeemed, non-revoked serial and its current product files.", "x-request-fields": [ "serial_id: integer (required)", "file_url: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serial_id": { "type": "integer", "minimum": 1 }, "file_url": { "type": "string" } }, "required": [ "serial_id" ], "additionalProperties": true } } } } } }, "/api/serials/export": { "get": { "summary": "Export serials as CSV for the signed-in developer.", "description": "Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "CSV export of the developer serial inventory.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/generate": { "post": { "summary": "Generate serial inventory for a product.", "description": "quantity defaults to 1; a supplied prefix must be exactly four alphanumeric characters. Reseller assignment requires an existing relationship. Side effects: Creates new available serials and can create billable external redemption capacity usage later.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "201": { "description": "Generated serial batch summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "customer_email": { "type": [ "string", "null" ] }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_count": { "type": "integer" }, "status": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "product_id: integer (required)", "quantity: integer", "prefix: string", "reseller_id: integer", "new_reseller_name: string", "expires_at: string,null", "promo_price: number", "promo_start: string,null", "promo_expires: string,null", "active_from: string,null", "active_to: string,null", "batch_tag: string", "notes: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "quantity": { "type": "integer", "minimum": 1 }, "prefix": { "type": "string" }, "reseller_id": { "type": "integer", "minimum": 1 }, "new_reseller_name": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "promo_price": { "type": "number" }, "promo_start": { "type": [ "string", "null" ], "format": "date-time" }, "promo_expires": { "type": [ "string", "null" ], "format": "date-time" }, "active_from": { "type": [ "string", "null" ], "format": "date-time" }, "active_to": { "type": [ "string", "null" ], "format": "date-time" }, "batch_tag": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "product_id" ], "additionalProperties": true } } } } } }, "/api/serials/import": { "post": { "summary": "Import serial inventory from CSV or file upload.", "description": "JSON serial rows, not a file upload. Requires serials.manage, all-products workspace scope and the existing external_serial_import billing-readiness check. Rows missing serialCode, a valid email or productName, or without an owned matching product, are skipped. Existing shared customer names, verification, status and preferences are not overwritten; per-serial name snapshots are retained. A serial and its historical transaction commit together, with any new customer rolled back on a duplicate race or failure. Earlier successful rows remain committed if a later row fails. Historical serials remain billing_eligible:false; this does not import provider payment authority, verify the inbox or override marketing preferences. Side effects: Creates serial records under the developer product catalog.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "Import summary and validation counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "count": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "serials: array (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js", "services/customerIdentityService.js", "services/legacySerialMutationService.js" ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serials": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "productName": { "type": "string" }, "serialCode": { "type": "string" }, "price": { "type": "number" }, "salePrice": { "type": "number" }, "downloadCount": { "type": "integer" }, "status": { "type": "string" }, "redeemDate": { "type": [ "string", "null" ], "format": "date-time" }, "date": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "required": [ "serials" ], "additionalProperties": true } } } } } }, "/api/serials/import-redeemed": { "post": { "summary": "Import owned-product redeemed serial rows without editing shared customer profiles", "description": "Legacy redeemed-serial CSV upload, distinct from JSON POST /api/serials/import. Send one multipart file field, not a JSON serials array. Required row values are Serial, Product and a valid Email. Optional columns: First Name, Last Name, Total Price, Purchase Date, Downloads, Revoked, Reseller, Country. Invalid required values, unknown/unowned products and duplicate serials are skipped; count reports inserted serials, not a per-row report. Existing shared customer names, verification, status and marketing preferences are not overwritten. A duplicate race or insert failure rolls back any new customer for that row. Earlier successful rows remain committed if a later row fails with 500 Import failed; do not assume file-level rollback. Imports remain billing_eligible:false and do not establish provider payment, inbox verification or a consent override.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: success, count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "count": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Operation-specific failure; inspect the linked reference and returned code before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "The supplied media or file type is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "serials.manage and all-products workspace scope; each product name must match a product owned by the effective developer.", "x-request-fields": [ "file: string (required). One CSV file with Serial, Product and Email columns; optional legacy serial-history columns are described in the guide." ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-error-codes": [ "developer_team_permission_denied", "developer_team_all_products_scope_required", "UPLOAD_TOO_LARGE", "UPLOAD_INVALID", "UPLOAD_INCOMPLETE", "UNSUPPORTED_FILE_TYPE" ], "x-source-files": [ "routes/importRedeemedSerialsRoute.js", "services/customerIdentityService.js", "middleware/developerTeamAuth.js", "middleware/uploadGuards.js" ], "deprecated": true, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "One CSV file with Serial, Product and Email columns; optional legacy serial-history columns are described in the guide." } }, "required": [ "file" ], "additionalProperties": true } } } } } }, "/api/serials/reassign/{id}": { "patch": { "summary": "Clear revocation on a legacy serial", "description": "Despite the legacy name, this handler clears revoked/revoked_at; it does not accept or assign a different customer email. Use current scoped customer-access workflows for identity changes.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The serial row after revoked/revoked_at are cleared.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "customer_email": { "type": [ "string", "null" ] }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_count": { "type": "integer" }, "status": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "serials.manage, owned product and assigned product access. Compatibility restore only; use current developer-scoped controls for new integrations.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/redeem": { "post": { "summary": "Redeem a serial from a customer-facing flow.", "description": "Requires a verified signed-in checkout account and uses the current account-owned redemption service. Body email/names do not select or overwrite another customer identity. Use /api/library/redeem-serial for new clients. Side effects: Can mark a serial redeemed and connect it to customer/product access.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "Redemption result, customer/product context, and access/download next step.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "serialCode": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "serialCode: string (required)", "email: string (required)", "firstName: string", "lastName: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js", "services/customerSerialRedemptionService.js", "middleware/checkoutAccountMiddleware.js" ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serialCode": { "type": "string" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } }, "required": [ "serialCode", "email" ], "additionalProperties": true } } } } } }, "/api/serials/redeemed": { "get": { "summary": "List redeemed serials for the signed-in developer.", "description": "Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "dateRange", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Rows with serial, customer, product, redemption date, status, revenue, and reseller labels.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "customer_email": { "type": [ "string", "null" ] }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_count": { "type": "integer" }, "status": { "type": "string" } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query page: integer", "query search: string", "query dateRange: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/refresh/{id}": { "patch": { "summary": "Reset legacy serial download tracking", "description": "Returns the updated serial row after resetting download_count and download logs. Legacy refresh_logs accounting is also written; this is not an activation reset or ordinary validation. Do not use it as a customer self-service device reset or infer current pricing from this legacy route. Side effects: Resets download tracking and can create a legacy accounting charge. Not a harmless read or activation reset.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The updated serial row; download_count is reset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "customer_email": { "type": [ "string", "null" ] }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_count": { "type": "integer" }, "status": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "serials.manage, the serial product owned by the effective developer workspace, and assigned product access. Foreign serial IDs are not available.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/resellers": { "get": { "summary": "List reseller/partner labels for serial workflows.", "description": "Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "Developer-scoped reseller relationship list.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "company_name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "additionalProperties": true } } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/revoke/{id}": { "patch": { "summary": "Revoke a serial.", "description": "Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs. Side effects: Can remove or block customer access tied to the serial.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated revoked serial/access state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "code": { "type": "string" }, "product_id": { "type": "integer", "minimum": 1 }, "customer_id": { "type": "integer", "minimum": 1 }, "customer_email": { "type": [ "string", "null" ] }, "redeemed": { "type": "boolean" }, "revoked": { "type": "boolean" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time" }, "download_count": { "type": "integer" }, "status": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "serials.manage, the serial product owned by the effective developer workspace, and assigned product access. Foreign serial IDs are not available.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/serials/serials/download/confirm": { "post": { "summary": "Confirm through the legacy compatibility alias.", "description": "Deprecated compatibility helper. Missing or foreign ownership is denied before reading counters or changing activity. Use entitlement delivery for new clients.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [], "responses": { "200": { "description": "200 JSON { success: true } after recording download activity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The customer account's owned, redeemed, non-revoked serial and its current product files.", "x-request-fields": [ "serial_id: integer (required)", "file_url: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serial_id": { "type": "integer", "minimum": 1 }, "file_url": { "type": "string" } }, "required": [ "serial_id", "file_url" ], "additionalProperties": true } } } } } }, "/api/serials/transactions": { "get": { "summary": "List serial-related transactions.", "description": "Legacy serial-table API, retained for existing clients. Use the current developer-scoped serial controls, customer-library redemption and product licensing API for new integrations. This path is not a replacement for the managed checkout, refund or payout APIs.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/serials" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "Transaction rows for serial/customer/product activity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query page: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/serialRoutes.js", "controllers/serialController.js" ], "deprecated": true } }, "/api/storefronts/{slug}": { "get": { "summary": "Fetch hosted public storefront brand/configuration by slug.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-embed" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public storefront payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1, "description": "Review IDs can be serialized strings; preserve the value when using moderation routes." }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "productSlug": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "imported": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "supportArticles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "type": { "type": "string" }, "visible": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ] } }, "/api/storefronts/{slug}/bundles": { "get": { "summary": "List public hosted bundle offers", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, bundles.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "slug": { "type": "string" } }, "additionalProperties": true }, "bundles": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "offerType": { "type": "string" }, "status": { "type": "string" }, "discountType": { "type": "string" }, "discountValue": { "type": "number" }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checkoutBacked": { "type": "boolean" }, "recurringAmountCents": { "type": "integer" }, "currency": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Published storefront and public offer visibility.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/storefronts/{slug}/bundles/{bundleSlug}": { "get": { "summary": "Read a hosted bundle offer", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bundleSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: storefront, bundle.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "slug": { "type": "string" } }, "additionalProperties": true }, "bundle": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "offerType": { "type": "string" }, "status": { "type": "string" }, "discountType": { "type": "string" }, "discountValue": { "type": "number" }, "productIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "subscriptionProductIds": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "products": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "checkoutBacked": { "type": "boolean" }, "recurringAmountCents": { "type": "integer" }, "currency": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Published storefront and public offer visibility.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/storefronts/{slug}/hise-catalog": { "get": { "summary": "Return a HISE-formatted storefront catalog.", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Catalog payload normalized for HISE storefront package use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ] }, "post": { "summary": "Return a HISE-formatted storefront catalog.", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Catalog payload normalized for HISE storefront package use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "search: string", "category: string", "limit: integer", "page: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string" }, "category": { "type": "string" }, "limit": { "type": "integer" }, "page": { "type": "integer" } }, "additionalProperties": true } } } } } }, "/api/storefronts/{slug}/newsletter": { "post": { "summary": "Submit storefront newsletter signup.", "description": "Newsletter signup can require confirmation. An existing suppression is not overridden; pending or emailSent does not mean subscribed. This path is separate from purchase-based enrollment. Side effects: Adds developer-scoped marketing/contact activity subject to consent and suppression rules.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Signup result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribed": { "type": "boolean" }, "alreadySubscribed": { "type": "boolean" }, "pending": { "type": "boolean" }, "verificationRequired": { "type": "boolean" }, "emailSent": { "type": "boolean" }, "contactId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "email: string (required)", "firstName: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" } }, "required": [ "email" ], "additionalProperties": true } } } } } }, "/api/storefronts/{slug}/newsletter/verify": { "get": { "summary": "Confirm a newsletter subscription using the private link", "description": "Consumes the verification link and changes subscription state. Do not poll, health-check, log or share this URL. Returns HTML success/error, not a customer session. This newsletter confirmation is distinct from purchase-related audience enrollment and does not override suppressions.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" } ], "responses": { "200": { "description": "HTTP 200: text/html.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "text/html": { "schema": { "type": "string" } } } }, "410": { "description": "The requested token or saved operation has expired.", "content": { "text/html": { "schema": { "type": "string" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "text/html": { "schema": { "type": "string" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Private newsletter verification token; no account session required.", "x-request-fields": [ "query token: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js" ] } }, "/api/storefronts/{slug}/products": { "get": { "summary": "List public products in a hosted storefront.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-embed" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" }, { "name": "minPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" }, "required": false, "description": "" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Public products/catalog payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [ "query page: integer", "query limit: integer", "query search: string", "query q: string", "query category: string", "query tag: string", "query type: string", "query platform: string", "query format: string", "query minPrice: number", "query maxPrice: number", "query sort: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ] } }, "/api/storefronts/{slug}/products/{productSlug}": { "get": { "summary": "Fetch a public storefront product detail.", "description": "Side effects: None for GET endpoints unless noted.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefront-embed" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public product detail payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "product": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1, "description": "Review IDs can be serialized strings; preserve the value when using moderation routes." }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "productSlug": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "imported": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Public, customer-token, developer-user, or scoped partner API surface as noted.", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ] } }, "/api/storefronts/{slug}/products/{productSlug}/reviews": { "get": { "summary": "Read paginated reviews of included bundle products", "description": "Bundle-only aggregate of published reviews for visible included products. A non-bundle without bundleReviews returns 404. The server clamps the requested page. verified reflects the stored entitlement association, not an independent endorsement or universal verification guarantee.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/embed-content" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" } ], "responses": { "200": { "description": "HTTP 200: reviews, summary, pagination, endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "productId": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "productName": { "type": "string" }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": "string" }, "verified": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "summary": { "type": "object", "properties": { "count": { "type": "integer" }, "averageRating": { "type": "number" } }, "additionalProperties": true }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "additionalProperties": true }, "endpoint": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Public published bundle with visible included products.", "x-request-fields": [ "query page: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/websitePageService.js", "services/storefrontService.js", "services/bundleReviewService.js" ] } }, "/api/storefronts/{slug}/reviews": { "get": { "summary": "List product/storefront reviews.", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "required": false, "description": "" }, { "name": "token", "in": "query", "schema": { "type": "string" }, "required": false, "description": "" } ], "responses": { "200": { "description": "Review list and customer-specific review affordances where available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1, "description": "Review IDs can be serialized strings; preserve the value when using moderation routes." }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "productSlug": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "imported": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } }, "summary": { "type": "object", "properties": { "count": { "type": "integer" }, "averageRating": { "type": "number" } }, "additionalProperties": true }, "eligibleProducts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query page: integer", "query limit: integer", "query token: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ] }, "post": { "summary": "Submit a storefront review.", "description": "Customer ownership/proof and moderation apply. Public browsing access is not permission to submit reviews. Imported reviews are not universally verified purchases.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created review or moderation state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "type": "object", "properties": { "id": { "type": [ "integer", "string" ], "minLength": 1, "description": "Review IDs can be serialized strings; preserve the value when using moderation routes." }, "productId": { "type": "integer", "minimum": 1 }, "productName": { "type": "string" }, "productSlug": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "title": { "type": "string" }, "body": { "type": "string" }, "customerName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedPurchase": { "type": "boolean" }, "imported": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "moderation": { "type": "object", "properties": { "status": { "type": "string" }, "awaitingApproval": { "type": "boolean" }, "message": { "type": "string" } }, "additionalProperties": true }, "automation": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "productId: integer (required)", "rating: integer (required)", "title: string", "body: string", "token: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js", "services/productReviewService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "token": { "type": "string" } }, "required": [ "productId", "rating" ], "additionalProperties": true } } } } } }, "/api/storefronts/{slug}/support": { "get": { "summary": "Load public storefront support settings.", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Support contact, policies, and help content configured for the storefront.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "support": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "type": { "type": "string" }, "visible": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "additionalProperties": true } }, "links": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ] } }, "/api/storefronts/{slug}/support/chat": { "post": { "summary": "Request storefront support chat assistance.", "description": "Support assistance can fall back to known storefront information if AI is unavailable. It does not submit the contact form, perform account actions, approve refunds or guarantee product compatibility.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Support chat answer/result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "answer": { "type": "object", "properties": { "reply": { "type": "string" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "needsContactForm": { "type": "boolean" }, "suggestedNextSteps": { "type": "array", "items": { "type": "string" } }, "matchedArticles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "body": { "type": "string" }, "type": { "type": "string" }, "visible": { "type": "boolean" }, "sortOrder": { "type": "integer" } }, "additionalProperties": true } }, "matchedProducts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "shortDescription": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "salePrice": { "type": [ "number", "null" ] }, "regularPrice": { "type": "number" }, "displayPrice": { "type": "number" }, "priceDisplay": { "type": "string" }, "regularPriceDisplay": { "type": "string" }, "salePriceDisplay": { "type": [ "string", "null" ] }, "isOnSale": { "type": "boolean" }, "currency": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "coverImage": { "type": [ "string", "null" ] }, "developerId": { "type": "integer", "minimum": 1 }, "developerName": { "type": "string" }, "developer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "additionalProperties": true }, "productType": { "type": "string" }, "productTypes": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "subscriptionEnabled": { "type": "boolean" }, "billingInterval": { "type": [ "string", "null" ] }, "checkoutEligible": { "type": "boolean" }, "capabilities": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." }, "requiresActivation": { "type": "boolean" }, "supportsSerials": { "type": "boolean" }, "supportsDownloads": { "type": "boolean" }, "marketplaceAsset": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } }, "source": { "type": "string" }, "aiUnavailable": { "type": "boolean" }, "unavailableReason": { "type": "string" } }, "additionalProperties": true }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "additionalProperties": true } }, "contactPrefill": { "type": "object", "additionalProperties": true, "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here." } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "message: string", "messages: array" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js", "services/developerSupportChatService.js" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } } } } }, "/api/storefronts/{slug}/support/requests": { "post": { "summary": "Create a storefront support request.", "description": "Requires the developer contact form to be enabled. A saved request and successful notification delivery are separate outcomes. Side effects: Creates developer-scoped support activity.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Support request creation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "request": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true }, "routedToDeveloper": { "type": "boolean" }, "emailSent": { "type": "boolean" }, "supportEmail": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "name: string", "email: string (required)", "subject: string", "message: string (required)", "productId: integer", "orderId: string" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "message": { "type": "string" }, "productId": { "type": "integer", "minimum": 1 }, "orderId": { "type": "string" } }, "required": [ "email", "message" ], "additionalProperties": true } } } } } }, "/api/storefronts/analytics": { "get": { "summary": "Resolve public tracking config for the requested host", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [ { "name": "host", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HTTP 200: enabled, measurementId, domain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "measurementId": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] } }, "additionalProperties": true } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "The operation-specific account, workspace, product and ownership checks apply.", "x-request-fields": [ "query host: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/storefrontRoutes.js", "services/developerGoogleAnalyticsService.js" ] } }, "/api/storefronts/domains/resolve": { "get": { "summary": "Resolve a custom domain to a storefront.", "description": "domain is an accepted host alias. This resolves public storefront routing, not DNS-provider control.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/storefronts" }, "parameters": [ { "name": "host", "in": "query", "schema": { "type": "string" }, "required": true, "description": "" } ], "responses": { "200": { "description": "Storefront/domain resolution result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "developerId": { "type": "integer", "minimum": 1 }, "storefront": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "tagline": { "type": "string" }, "logoUrl": { "type": "string" }, "lightLogoUrl": { "type": "string" }, "darkLogoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "accentColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "themeMode": { "type": "string" }, "publicUrl": { "type": "string" }, "customDomain": { "type": [ "string", "null" ] }, "supportEmail": { "type": "string" } }, "additionalProperties": true }, "domain": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "domain": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true } }, "sslStatus": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Service failure; an uncertain side effect must be reconciled before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Product or storefront scoped", "x-request-fields": [ "query host: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-request-body": "No body fields are read by this operation.", "x-source-files": [ "routes/storefrontRoutes.js", "services/storefrontService.js" ] } }, "/api/subscriptions/bundles/{bundleId}": { "get": { "summary": "Read a published bundle and its current version.", "description": "Public read; unpublished or unavailable bundles cannot be used for checkout. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [ { "name": "bundleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ bundle } with interval, amounts, trial/grace settings, membershipMode, fulfillmentMode, versionId, and products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "fulfillmentMode": { "enum": [ "access", "keep_products" ] }, "membershipMode": { "enum": [ "selected_products", "all_products" ] }, "billingInterval": { "type": "string" }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "required": [ "bundle" ], "additionalProperties": true } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Public request; operation-specific verification still applies", "x-access-scope": "Published and available bundle data only; no private customer or subscription records.", "x-request-fields": [ "bundleId path" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js" ] } }, "/api/subscriptions/bundles/billing-portal": { "post": { "summary": "Open the permitted provider billing portal", "description": "Side effects: Create an authorized customer billing-portal session. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: url, sessionId, expiresAt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "sessionId": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "bundleSubscriptionId: integer", "standaloneSubscriptionId: integer", "historyOnly: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js", "services/subscriptionBundleService.js", "services/subscriptionPaymentMethodService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundleSubscriptionId": { "type": "integer", "minimum": 1 }, "standaloneSubscriptionId": { "type": "integer", "minimum": 1 }, "historyOnly": { "type": "boolean" } }, "additionalProperties": true, "oneOf": [ { "required": [ "bundleSubscriptionId" ], "not": { "required": [ "standaloneSubscriptionId" ] } }, { "required": [ "standaloneSubscriptionId" ], "not": { "required": [ "bundleSubscriptionId" ] } } ] } } } } } }, "/api/subscriptions/bundles/cancel": { "post": { "summary": "Schedule the supported cancellation at period end.", "description": "Cancellation is not a refund. Previously earned keep-products ownership remains unless its source payment is reversed. Side effects: Schedule the supported cancellation at period end. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [], "responses": { "200": { "description": "Current cancellation/subscription result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "type": "object", "properties": { "status": { "type": "string" }, "cancel_at_period_end": { "type": "boolean" } }, "additionalProperties": true }, "immediate": { "type": "boolean" }, "alreadyEnded": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "bundleSubscriptionId: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js", "services/subscriptionBundleService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundleSubscriptionId": { "type": "integer", "minimum": 1 } }, "required": [ "bundleSubscriptionId" ], "additionalProperties": true } } } } } }, "/api/subscriptions/bundles/cancel-scheduled-change": { "post": { "summary": "Cancel an eligible pending plan change", "description": "Side effects: Remove a pending supported plan change. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: canceled, changeId, subscriptionId.", "content": { "application/json": { "schema": { "type": "object", "properties": { "canceled": { "type": "boolean" }, "changeId": { "type": "integer", "minimum": 1 }, "subscriptionId": { "type": "integer", "minimum": 1 } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "bundleSubscriptionId: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js", "services/subscriptionBundleService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundleSubscriptionId": { "type": "integer", "minimum": 1 } }, "required": [ "bundleSubscriptionId" ], "additionalProperties": true } } } } } }, "/api/subscriptions/bundles/cancel-standalone": { "post": { "summary": "Cancel standalone renewal at paid-period end", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [], "responses": { "200": { "description": "{ subscription }; an ended subscription can return alreadyEnded: true, with duplicate: true when already ended locally. Inspect paid-through access and the returned state rather than treating every response as a new cancellation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "type": "object", "properties": {}, "additionalProperties": true }, "duplicate": { "type": "boolean" }, "alreadyEnded": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "standaloneSubscriptionId: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "standaloneSubscriptionId": { "type": "integer", "minimum": 1 } }, "required": [ "standaloneSubscriptionId" ], "additionalProperties": true } } } } } }, "/api/subscriptions/bundles/change-confirm": { "post": { "summary": "Confirm a still-valid plan preview.", "description": "Do not reuse a stale preview or create a second payment after an uncertain response. Side effects: Confirm a still-valid plan preview. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [], "responses": { "200": { "description": "Successful idempotent replay or duplicate confirmation; inspect the linked operation contract.", "content": { "application/json": { "schema": { "type": "object", "properties": { "duplicate": { "type": "boolean" }, "change": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" } }, "additionalProperties": true }, "preview": { "type": "object", "properties": { "effectiveMode": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "201": { "description": "201 for a new confirmation or 200 for a duplicate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "duplicate": { "type": "boolean" }, "change": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" } }, "additionalProperties": true }, "preview": { "type": "object", "properties": { "effectiveMode": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "previewId: string (required)", "idempotencyKey: string (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js", "services/subscriptionBundleService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "previewId": { "type": "string", "format": "uuid" }, "idempotencyKey": { "type": "string" } }, "required": [ "previewId", "idempotencyKey" ], "additionalProperties": true } } } } } }, "/api/subscriptions/bundles/change-preview": { "post": { "summary": "Inspect a proposed plan change and its timing.", "description": "The current subscription must belong to the signed-in buyer. Read the preview before confirmation. Side effects: Inspect a proposed plan change and its timing. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [], "responses": { "201": { "description": "201: preview, proposed timing, amounts, and conflict context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "effectiveMode": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "currentSubscriptionId: integer (required)", "targetBundleId: integer (required)", "effectiveMode: immediate | next_renewal" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentSubscriptionId": { "type": "integer", "minimum": 1 }, "targetBundleId": { "type": "integer", "minimum": 1 }, "effectiveMode": { "enum": [ "immediate", "next_renewal" ] } }, "required": [ "currentSubscriptionId", "targetBundleId" ], "additionalProperties": true } } } } } }, "/api/subscriptions/bundles/checkout": { "post": { "summary": "Create a Stripe checkout session for the signed-in buyer.", "description": "The server supplies buyer identity and required environment. Keep-products ownership requires eligible live payment evidence; a session URL does not grant ownership. Side effects: Create a Stripe checkout session for the signed-in buyer. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Reuse for the same logical checkout; do not change the request under the same key." } ], "responses": { "201": { "description": "201: provider, checkoutSessionId, url, customerId, bundle, and conflicts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "stripe" }, "checkoutSessionId": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "customerId": { "type": "integer", "minimum": 1 }, "bundle": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "fulfillmentMode": { "enum": [ "access", "keep_products" ] }, "membershipMode": { "enum": [ "selected_products", "all_products" ] }, "billingInterval": { "type": "string" }, "recurringAmountCents": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "integer", "minimum": 1 }, "name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "conflicts": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "header Idempotency-Key: string. Reuse for the same logical checkout; do not change the request under the same key.", "bundleId: integer (required)", "promoCode: string", "taxQuoteId: string", "idempotencyKey: string", "marketingOptOut: boolean", "marketingOptIn: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundleId": { "type": "integer", "minimum": 1 }, "promoCode": { "type": "string" }, "taxQuoteId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "marketingOptOut": { "type": "boolean" }, "marketingOptIn": { "type": "boolean" } }, "required": [ "bundleId" ], "additionalProperties": true } } } } } }, "/api/subscriptions/bundles/customer/subscriptions": { "get": { "summary": "List the signed-in customer's subscriptions for one developer.", "description": "The server resolves the customer from the signed-in user; do not supply another customer identity. Side effects: Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [ { "name": "developerId", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "{ subscriptions } or an empty list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "subscriptions" ], "additionalProperties": true } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "query developerId: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js" ] } }, "/api/subscriptions/bundles/manual-billing-confirm": { "post": { "summary": "Confirm the supported billing setup", "description": "Side effects: Confirm the reviewed manual-grant billing amount. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: success, amountCents, taxAmountCents, totalCents, currency, productName, sessionId, subscriptionId, kind.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "amountCents": { "type": "integer", "minimum": 0 }, "taxAmountCents": { "type": "integer", "minimum": 0 }, "totalCents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "productName": { "type": "string" }, "sessionId": { "type": "string" }, "subscriptionId": { "type": "integer", "minimum": 1 }, "kind": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "kind: bundle | standalone (required)", "subscriptionId: integer (required)", "sessionId: string (required)", "expectedTotalCents: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js", "services/manualGrantBillingService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "bundle", "standalone" ] }, "subscriptionId": { "type": "integer", "minimum": 1 }, "sessionId": { "type": "string" }, "expectedTotalCents": { "type": "integer", "minimum": 0 } }, "required": [ "kind", "subscriptionId", "sessionId", "expectedTotalCents" ], "additionalProperties": true } } } } } }, "/api/subscriptions/bundles/manual-billing-preview": { "post": { "summary": "Preview the proposed billing conversion", "description": "Side effects: Preview billing after the customer completes setup. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "200": { "description": "HTTP 200: success, amountCents, taxAmountCents, totalCents, currency, productName, sessionId, subscriptionId, kind.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "amountCents": { "type": "integer", "minimum": 0 }, "taxAmountCents": { "type": "integer", "minimum": 0 }, "totalCents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "productName": { "type": "string" }, "sessionId": { "type": "string" }, "subscriptionId": { "type": "integer", "minimum": 1 }, "kind": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "kind: bundle | standalone (required)", "subscriptionId: integer (required)", "sessionId: string (required)", "expectedTotalCents: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js", "services/manualGrantBillingService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "bundle", "standalone" ] }, "subscriptionId": { "type": "integer", "minimum": 1 }, "sessionId": { "type": "string" }, "expectedTotalCents": { "type": "integer", "minimum": 0 } }, "required": [ "kind", "subscriptionId", "sessionId" ], "additionalProperties": true } } } } } }, "/api/subscriptions/bundles/manual-billing-setup": { "post": { "summary": "Start customer-authorized billing setup for a manual grant", "description": "Side effects: Begin billing setup for an eligible manually granted subscription. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/current-operations" }, "parameters": [], "responses": { "201": { "description": "HTTP 201: url, sessionId.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "sessionId": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "kind: bundle | standalone (required)", "subscriptionId: integer (required)", "sessionId: string", "expectedTotalCents: integer" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js", "services/manualGrantBillingService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "bundle", "standalone" ] }, "subscriptionId": { "type": "integer", "minimum": 1 }, "sessionId": { "type": "string" }, "expectedTotalCents": { "type": "integer", "minimum": 0 } }, "required": [ "kind", "subscriptionId" ], "additionalProperties": true } } } } } }, "/api/subscriptions/bundles/payment-update": { "post": { "summary": "Start payment-method setup", "description": "", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [], "responses": { "200": { "description": "Card setup returns { url, sessionId }; invoice authentication returns { url }. Open the returned provider URL. Completion is verified by the signed provider callback, not by the browser return alone.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "sessionId": { "type": "string" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "bundleSubscriptionId: integer", "standaloneSubscriptionId: integer", "authenticate: boolean" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js", "services/subscriptionBundleService.js", "services/subscriptionPaymentMethodService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundleSubscriptionId": { "type": "integer", "minimum": 1 }, "standaloneSubscriptionId": { "type": "integer", "minimum": 1 }, "authenticate": { "type": "boolean" } }, "additionalProperties": true, "oneOf": [ { "required": [ "bundleSubscriptionId" ], "not": { "required": [ "standaloneSubscriptionId" ] } }, { "required": [ "standaloneSubscriptionId" ], "not": { "required": [ "bundleSubscriptionId" ] } } ] } } } } } }, "/api/subscriptions/bundles/reactivate": { "post": { "summary": "Resume an eligible plan before the cancellation takes effect.", "description": "Eligibility is checked against the current plan and provider state. Side effects: Resume an eligible plan before the cancellation takes effect. Review the confirmation and retry requirements before repeating the request.", "externalDocs": { "url": "https://www.soundsync.dev/docs/api/subscription-bundles" }, "parameters": [], "responses": { "200": { "description": "Current subscription/reactivation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "type": "object", "properties": { "status": { "type": "string" }, "cancel_at_period_end": { "type": "boolean" } }, "additionalProperties": true }, "immediate": { "type": "boolean" }, "alreadyEnded": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or challenge state; inspect the route-specific code and field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, invalid, or expired authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Authenticated context is not permitted for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The permitted resource or account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Current state conflicts with the requested change; reload and reconcile before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "A required service is temporarily unavailable; inspect the failure before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Operation-specific failure. Error fields vary by route; do not infer retry safety from status alone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "x-authentication": "Account Bearer JWT", "x-access-scope": "The signed-in buyer's subscription and authorized provider billing relationship.", "x-request-fields": [ "bundleSubscriptionId: integer (required)" ], "x-evidence": "Source-reviewed reference. Not a claim of seeded E2 coverage or native-host runtime verification for every operation.", "security": [ { "AccountSession": [] } ], "x-contract-coverage": "Reviewed field schemas; inspect linked guide for conditional fields and complete state handling.", "x-source-files": [ "routes/subscriptionBundleRoutes.js", "services/subscriptionBundleService.js" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundleSubscriptionId": { "type": "integer", "minimum": 1 } }, "required": [ "bundleSubscriptionId" ], "additionalProperties": true } } } } } } } }